tessl/npm-nuxt--kit

Toolkit for authoring modules and interacting with Nuxt

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Plugins & Templates

Name: tessl/npm-nuxt--kit
Author: tessl

Plugin registration and template generation for virtual file system and TypeScript support. Manages both runtime plugins and build-time template generation.

Capabilities

Plugin Registration

/**
 * Register a Nuxt plugin
 * @param plugin - Plugin file path or plugin object
 * @param opts - Plugin registration options
 * @returns Normalized NuxtPlugin object
 */
function addPlugin(
  plugin: NuxtPlugin | string,
  opts?: AddPluginOptions
): NuxtPlugin;

/**
 * Add template and register as plugin
 * @param plugin - Plugin template or file path
 * @param opts - Plugin registration options
 * @returns Normalized NuxtPlugin object
 */
function addPluginTemplate(
  plugin: NuxtPluginTemplate | string,
  opts?: AddPluginOptions
): NuxtPlugin;

/**
 * Normalize plugin object
 * @param plugin - Plugin to normalize
 * @returns Normalized NuxtPlugin object
 */
function normalizePlugin(plugin: NuxtPlugin | string): NuxtPlugin;

interface NuxtPlugin {
  /** Plugin source code or file path */
  src: string;
  /** Plugin execution mode */
  mode?: PluginMode;
  /** Plugin runs only once */
  ssr?: boolean;
  /** Plugin name */
  name?: string;
  /** Plugin priority */
  order?: number;
  /** Plugin environment */
  env?: PluginEnv;
  /** Plugin metadata */
  meta?: PluginMeta;
}

type PluginMode = "client" | "server" | "all";
type PluginEnv = { islands?: boolean };

interface AddPluginOptions {
  /** Append plugin to end of array */
  append?: boolean;
  /** Prepend plugin to beginning of array */
  prepend?: boolean;
}

interface PluginMeta {
  /** Plugin name */
  name?: string;
  /** Plugin version */
  version?: string;
  [key: string]: any;
}

Usage Examples:

import { addPlugin, addPluginTemplate } from "@nuxt/kit";

// Add existing plugin file
addPlugin("~/plugins/my-plugin.client.js");

// Add plugin with options
addPlugin({
  src: "~/plugins/analytics.js",
  mode: "client",
  name: "analytics-plugin"
});

// Add plugin template
addPluginTemplate({
  src: "~/templates/api-plugin.mjs",
  filename: "api-plugin.mjs",
  options: {
    apiEndpoint: "https://api.example.com",
    timeout: 5000
  }
});

// Add inline plugin
addPlugin({
  name: "inline-setup",
  setup() {
    // Plugin code here
    console.log("Plugin initialized");
  }
});

Template System

Generate virtual files and manage the template system for build-time code generation.

/**
 * Add template to virtual file system
 * @param template - Template configuration or file path
 * @returns Resolved template object
 */
function addTemplate<T>(template: NuxtTemplate<T> | string): ResolvedNuxtTemplate<T>;

/**
 * Add virtual file for Nuxt Nitro server build
 * @param template - Server template configuration
 * @returns Server template object
 */
function addServerTemplate(template: NuxtServerTemplate): NuxtServerTemplate;

/**
 * Add type template and register as TypeScript reference
 * @param template - Type template configuration
 * @param context - Template context options
 * @returns Resolved template object
 */
function addTypeTemplate<T>(
  template: NuxtTypeTemplate<T>,
  context?: { nitro?: boolean; nuxt?: boolean }
): ResolvedNuxtTemplate<T>;

/**
 * Normalize template object
 * @param template - Template to normalize
 * @param buildDir - Build directory path
 * @returns Resolved template object
 */
function normalizeTemplate<T>(
  template: NuxtTemplate<T> | string,
  buildDir?: string
): ResolvedNuxtTemplate<T>;

interface NuxtTemplate<T = Record<string, any>> {
  /** Template source file path */
  src?: string;
  /** Output filename */
  filename?: string;
  /** Template destination path */
  dst?: string;
  /** Template data/options */
  options?: T;
  /** Template content generator */
  getContents?: (data: T) => string | Promise<string>;
  /** Write template to filesystem */
  write?: boolean;
  /** Template metadata */
  meta?: TemplateMeta;
}

interface ResolvedNuxtTemplate<T = Record<string, any>> extends NuxtTemplate<T> {
  /** Resolved destination path */
  dst: string;
  /** Resolved filename */
  filename: string;
}

interface TemplateMeta {
  /** Template component */
  component?: boolean;
  [key: string]: any;
}

Usage Examples:

import { addTemplate, addTypeTemplate, addServerTemplate } from "@nuxt/kit";

// Add simple template
addTemplate({
  filename: "my-config.mjs",
  getContents: () => `export default ${JSON.stringify(myConfig)}`
});

// Add template with data
addTemplate({
  src: "templates/api-client.mjs",
  filename: "api-client.mjs",
  options: {
    baseURL: "https://api.example.com",
    timeout: 5000
  }
});

// Add TypeScript type template
addTypeTemplate({
  filename: "types/my-module.d.ts",
  getContents: () => `
    declare module '#app' {
      interface NuxtApp {
        $myModule: MyModuleInterface
      }
    }
    
    export interface MyModuleInterface {
      method(): void;
    }
  `
});

// Add server-only template
addServerTemplate({
  src: "templates/server-utils.mjs",
  filename: "server-utils.mjs"
});

Plugin Templates

Combine plugins with templates for dynamic plugin generation.

interface NuxtPluginTemplate<T = Record<string, any>> extends NuxtTemplate<T> {
  /** Plugin execution mode */
  mode?: PluginMode;
  /** Plugin runs server-side */
  ssr?: boolean;
  /** Plugin order */
  order?: number;
}

Usage Examples:

import { addPluginTemplate } from "@nuxt/kit";

// Dynamic plugin with configuration
addPluginTemplate({
  src: "templates/auth-plugin.mjs",
  filename: "auth-plugin.mjs",
  mode: "all",
  options: {
    providers: ["google", "github"],
    redirectUrl: "/dashboard"
  }
});

// Inline plugin template
addPluginTemplate({
  filename: "runtime-config-plugin.mjs",
  mode: "client",
  getContents: (options) => `
    export default defineNuxtPlugin(() => {
      const config = ${JSON.stringify(options.config)};
      return {
        provide: {
          config
        }
      };
    });
  `,
  options: {
    config: { apiUrl: "https://api.example.com" }
  }
});

Template Management

Control template lifecycle and updates.

/**
 * Trigger rebuilding Nuxt templates
 * @param options - Template update options
 * @returns Promise resolving when templates are updated
 */
function updateTemplates(
  options?: { filter?: (template: ResolvedNuxtTemplate<any>) => boolean }
): Promise<void>;

/**
 * Write TypeScript configuration and declarations
 * @param nuxt - Nuxt instance
 * @returns Promise resolving when types are written
 */
function writeTypes(nuxt: Nuxt): Promise<void>;

Usage Examples:

import { updateTemplates, writeTypes } from "@nuxt/kit";

// Update all templates
await updateTemplates();

// Update specific templates
await updateTemplates({
  filter: (template) => template.filename.includes("api")
});

// Write TypeScript declarations
await writeTypes(nuxt);

Advanced Template Patterns

Conditional Templates:

import { addTemplate } from "@nuxt/kit";

export default defineNuxtModule({
  setup(options, nuxt) {
    // Only add template in development
    if (nuxt.options.dev) {
      addTemplate({
        filename: "dev-tools.mjs",
        getContents: () => `
          export function devLog(message) {
            console.log('[DEV]', message);
          }
        `
      });
    }
  }
});

Template with External Data:

import { addTemplate } from "@nuxt/kit";
import { readFileSync } from "fs";

addTemplate({
  filename: "build-info.mjs",
  getContents: async () => {
    const packageJson = JSON.parse(readFileSync("package.json", "utf-8"));
    const buildTime = new Date().toISOString();
    
    return `
      export const buildInfo = {
        version: "${packageJson.version}",
        buildTime: "${buildTime}",
        environment: "${process.env.NODE_ENV}"
      };
    `;
  }
});

Types

interface NuxtServerTemplate extends NuxtTemplate {
  /** Template is for server-side only */
  island?: boolean;
}

interface NuxtTypeTemplate<T = Record<string, any>> extends NuxtTemplate<T> {
  /** Generate TypeScript declaration file */
  declaration?: boolean;
}

Install with Tessl CLI