feat: add npm template support

Add support for using npm packages as templates when creating new projects.
This feature allows users to specify custom templates from npm registry
with optional version control.

- Support multiple npm template formats (npm:, @scope/package, package-name)
- Add --template-version flag for version specification
- Implement smart caching mechanism (.temp-templates/)
- Support flexible template structures (template/, templates/app/, root)
- Export utility functions for downstream projects

Author: Huxpro

README.md

@@ -17,6 +17,65 @@ A shared package for create-rspack, create-rsbuild, create-rspress and create-rs
 npm add create-rstack -D
 ```
 
+## Features
+
+### NPM Template Support
+
+`create-rstack` supports using npm packages as templates, allowing users to create projects from custom templates published to npm.
+
+#### Usage
+
+```bash
+# Using npm package name
+npm create rsbuild@latest my-project -- --template my-template-package
+
+# Using scoped package
+npm create rsbuild@latest my-project -- --template @scope/template-package
+
+# Using explicit npm: prefix
+npm create rsbuild@latest my-project -- --template npm:my-template-package
+
+# With specific version
+npm create rsbuild@latest my-project -- --template my-template-package --template-version 1.2.3
+```
+
+#### Template Package Structure
+
+Your npm template package should have one of the following structures:
+
+```
+my-template-package/
+├── template/              # Preferred
+│   ├── package.json
+│   └── src/
+├── templates/
+│   └── app/              # Alternative
+└── (root)                # Fallback
+    ├── package.json
+    └── src/
+```
+
+#### Caching Strategy
+
+- Templates with `latest` version are always re-installed to ensure the latest version
+- Specific versions are cached in `.temp-templates/` for faster reuse
+
+#### API
+
+```typescript
+import {
+  isNpmTemplate,
+  resolveCustomTemplate,
+  resolveNpmTemplate,
+} from 'create-rstack';
+
+// Check if template input is an npm package
+if (isNpmTemplate(templateInput)) {
+  // Resolve npm template to local path
+  const templatePath = resolveCustomTemplate(templateInput, version);
+}
+```
+
 ## Examples
 
 | Project | Link                                                                                         |

src/index.ts

@@ -23,8 +23,18 @@ import { x } from 'tinyexec';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 
+import { isNpmTemplate, resolveCustomTemplate } from './template-manager.js';
+
 export { autocomplete, groupMultiselect, multiselect, select, text };
 
+// Export npm template utilities
+export {
+  isNpmTemplate,
+  resolveCustomTemplate,
+  resolveNpmTemplate,
+  sanitizeCacheKey,
+} from './template-manager.js';
+
 function cancelAndExit() {
   cancel('Operation cancelled.');
   process.exit(0);
@@ -113,6 +123,8 @@ export type Argv = {
   skill?: string | string[];
   packageName?: string;
   'package-name'?: string;
+  templateVersion?: string;
+  'template-version'?: string;
 };
 
 export const BUILTIN_TOOLS = ['eslint', 'rslint', 'biome', 'prettier'];
@@ -163,6 +175,7 @@ function logHelpMessage(
       --tools <tool>        add additional tools, comma separated
 ${skillsOptionLine}      --override            override files in target directory
       --packageName <name>  specify the package name
+      --template-version <ver>  specify the npm template version
     
     Available templates:
       ${templates.join(', ')}
@@ -341,6 +354,11 @@ const parseArgv = (processArgv: string[]) => {
     argv.packageName = argv['package-name'];
   }
 
+  // Handle template-version alias
+  if (argv['template-version']) {
+    argv.templateVersion = argv['template-version'];
+  }
+
   return argv;
 };
 
@@ -592,6 +610,48 @@ export async function create({
   }
 
   const templateName = await getTemplateName(argv);
+
+  const srcFolder = path.join(root, `template-${templateName}`);
+
+  // Handle npm template: only when the local template doesn't exist
+  // and the template input looks like an npm package
+  if (
+    typeof argv.template === 'string' &&
+    isNpmTemplate(argv.template) &&
+    !fs.existsSync(srcFolder)
+  ) {
+    const templateVersion = argv.templateVersion ?? argv['template-version'];
+    const templatePath = resolveCustomTemplate(argv.template, templateVersion, {
+      cacheDir: root,
+    });
+
+    // Copy npm template directly to distFolder
+    copyFolder({
+      from: templatePath,
+      to: distFolder,
+      version,
+      packageName,
+      templateParameters,
+      skipFiles,
+    });
+
+    const nextSteps = noteInformation
+      ? noteInformation
+      : [
+          `1. ${color.cyan(`cd ${targetDir}`)}`,
+          `2. ${color.cyan('git init')} ${color.dim('(optional)')}`,
+          `3. ${color.cyan(`${packageManager} install`)}`,
+          `4. ${color.cyan(`${packageManager} run dev`)}`,
+        ];
+
+    if (nextSteps.length) {
+      note(nextSteps.map((step) => color.reset(step)).join('\n'), 'Next steps');
+    }
+
+    outro('All set, happy coding!');
+    return;
+  }
+
   const tools = await getTools(argv, extraTools, templateName);
   const skills = await getSkills(
     argv,
@@ -601,7 +661,6 @@ export async function create({
     multiselect,
   );
 
-  const srcFolder = path.join(root, `template-${templateName}`);
   const commonFolder = path.join(root, 'template-common');
 
   if (!fs.existsSync(srcFolder)) {

src/template-manager.ts

@@ -0,0 +1,151 @@
+import { execSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const NPM_TEMPLATE_PREFIX = 'npm:';
+
+/**
+ * Sanitize package name and version to create a valid cache key
+ */
+export const sanitizeCacheKey = (packageName: string, version: string) => {
+  // Keep the slash for scoped packages (e.g., @scope/package)
+  // but replace other slashes that would be invalid in file paths
+  const normalized = packageName.startsWith('@')
+    ? packageName
+    : packageName.replace(/[\\/]/g, '_');
+  const versionLabel = version || 'latest';
+  return `${normalized}@${versionLabel}`;
+};
+
+/**
+ * Check if the input is an npm package template
+ */
+export function isNpmTemplate(templateInput: string): boolean {
+  const trimmedInput = templateInput.trim();
+
+  // Explicit npm: prefix
+  if (trimmedInput.startsWith(NPM_TEMPLATE_PREFIX)) {
+    return true;
+  }
+
+  // Scoped package (@scope/package) or pure package name (no path separators)
+  if (
+    trimmedInput.startsWith('@') ||
+    (!trimmedInput.includes('/') &&
+      !trimmedInput.startsWith('http') &&
+      !trimmedInput.startsWith('.') &&
+      !trimmedInput.startsWith('github:'))
+  ) {
+    return true;
+  }
+
+  return false;
+}
+
+/**
+ * Resolve npm template package and return the local path
+ */
+export function resolveNpmTemplate(
+  packageName: string,
+  version?: string,
+  options?: { forceLatest?: boolean; cacheDir?: string },
+): string {
+  const normalizedName = packageName.trim();
+
+  // Handle version
+  const versionSpecifier =
+    version?.trim() && version.trim().toLowerCase() !== 'latest'
+      ? version.trim()
+      : 'latest';
+
+  // Generate cache key
+  const cacheKey = sanitizeCacheKey(normalizedName, versionSpecifier);
+  const cacheRoot = options?.cacheDir || process.cwd();
+  const templateDir = path.join(cacheRoot, '.temp-templates', cacheKey);
+  const installRoot = path.dirname(templateDir);
+  const packagePath = path.join(installRoot, 'node_modules', normalizedName);
+
+  // Check if we should reuse cache
+  const forceLatest = options?.forceLatest ?? versionSpecifier === 'latest';
+  const shouldReuseCache = !forceLatest && fs.existsSync(templateDir);
+
+  if (shouldReuseCache) {
+    return templateDir;
+  }
+
+  // Create isolated package.json to prevent workspace conflicts
+  const anchorPkgJson = path.join(installRoot, 'package.json');
+  if (!fs.existsSync(anchorPkgJson)) {
+    const minimal = { name: 'create-rstack-template-cache', private: true };
+    fs.writeFileSync(
+      anchorPkgJson,
+      `${JSON.stringify(minimal, null, 2)}\n`,
+      'utf8',
+    );
+  }
+
+  // Install the package
+  try {
+    execSync(
+      `npm install ${normalizedName}@${versionSpecifier} --no-save --package-lock=false --no-audit --no-fund --silent`,
+      {
+        cwd: installRoot,
+        stdio: 'pipe',
+      },
+    );
+  } catch {
+    throw new Error(
+      `Failed to install npm template "${normalizedName}@${versionSpecifier}". Please check if the package exists.`,
+    );
+  }
+
+  // Find template directory (by priority)
+  const possibleTemplatePaths = [
+    path.join(packagePath, 'template'), // Priority: package/template
+    path.join(packagePath, 'templates', 'app'),
+    path.join(packagePath, 'templates', 'default'),
+    packagePath, // Fallback: package root
+  ];
+
+  for (const pathCandidate of possibleTemplatePaths) {
+    if (
+      fs.existsSync(pathCandidate) &&
+      fs.statSync(pathCandidate).isDirectory()
+    ) {
+      // Copy to cache directory
+      fs.mkdirSync(templateDir, { recursive: true });
+      // eslint-disable-next-line n/no-unsupported-features/node-builtins
+      fs.cpSync(pathCandidate, templateDir, { recursive: true });
+      return templateDir;
+    }
+  }
+
+  throw new Error(
+    `No valid template directory found in package "${normalizedName}". Expected one of: template/, templates/app/, templates/default/, or package root.`,
+  );
+}
+
+/**
+ * Resolve custom template (npm package, GitHub, or local path)
+ */
+export function resolveCustomTemplate(
+  templateInput: string,
+  version?: string,
+  options?: { forceLatest?: boolean; cacheDir?: string },
+): string {
+  const trimmedInput = templateInput.trim();
+
+  // Handle npm: prefix explicitly
+  if (trimmedInput.startsWith(NPM_TEMPLATE_PREFIX)) {
+    const packageName = trimmedInput.slice(NPM_TEMPLATE_PREFIX.length).trim();
+    return resolveNpmTemplate(packageName, version, options);
+  }
+
+  // Handle scoped package or pure package name
+  if (isNpmTemplate(trimmedInput)) {
+    return resolveNpmTemplate(trimmedInput, version, options);
+  }
+
+  // For GitHub URLs or local paths, return as-is (handled by create-rstack)
+  return trimmedInput;
+}

test/index.test.ts

@@ -3,7 +3,11 @@ import { expect, test } from '@rstest/core';
 import {
   checkCancel,
   create,
+  isNpmTemplate,
   multiselect,
+  resolveCustomTemplate,
+  resolveNpmTemplate,
+  sanitizeCacheKey,
   select,
   text,
 } from '../dist/index.js';
@@ -22,3 +26,39 @@ test('should expose selected clack prompt helpers from src entrypoint', () => {
   expect(publicApi.multiselect).toBe(promptsActual.multiselect);
   expect(publicApi.groupMultiselect).toBe(promptsActual.groupMultiselect);
 });
+
+test('should export npm template utilities', () => {
+  expect(typeof isNpmTemplate).toBe('function');
+  expect(typeof resolveCustomTemplate).toBe('function');
+  expect(typeof resolveNpmTemplate).toBe('function');
+  expect(typeof sanitizeCacheKey).toBe('function');
+});
+
+test('should detect npm templates correctly', () => {
+  // npm: prefix
+  expect(isNpmTemplate('npm:my-package')).toBe(true);
+  expect(isNpmTemplate('npm:@scope/package')).toBe(true);
+
+  // Scoped packages
+  expect(isNpmTemplate('@scope/package')).toBe(true);
+
+  // Pure package names
+  expect(isNpmTemplate('my-package')).toBe(true);
+  expect(isNpmTemplate('my-package-name')).toBe(true);
+
+  // Not npm templates
+  expect(isNpmTemplate('./local-path')).toBe(false);
+  expect(isNpmTemplate('../relative-path')).toBe(false);
+  expect(isNpmTemplate('github:user/repo')).toBe(false);
+  expect(isNpmTemplate('https://example.com')).toBe(false);
+  expect(isNpmTemplate('/absolute/path')).toBe(false);
+});
+
+test('should sanitize cache keys correctly', () => {
+  expect(sanitizeCacheKey('my-package', '1.0.0')).toBe('my-package@1.0.0');
+  expect(sanitizeCacheKey('@scope/package', 'latest')).toBe(
+    '@scope/package@latest',
+  );
+  expect(sanitizeCacheKey('my-package', '')).toBe('my-package@latest');
+  expect(sanitizeCacheKey('my/package', '1.0.0')).toBe('my_package@1.0.0');
+});