create-packkit 2.0.3 → 2.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-packkit",
-  "version": "2.0.3",
+  "version": "2.2.0",
   "description": "Highly configurable scaffolder for modern npm packages and CLIs — pick your stack (TS/JS, bundler, tests, linter, CI, releases) from a CLI or a web configurator.",
   "type": "module",
   "bin": {

package/src/cli/args.js

@@ -23,6 +23,7 @@ const OVERRIDE_FLAGS = {
 // Boolean options that default ON — a --no-<flag> turns them off.
 const NEGATABLE = {
   'no-coverage': 'coverage',
+  'no-sourcemaps': 'sourcemaps',
   'no-community': 'community',
   'no-agents': 'agents',
   'no-vscode': 'vscode',
@@ -48,6 +49,9 @@ export function parseCliArgs(argv) {
       minify: { type: 'boolean' },
       monorepo: { type: 'boolean' },
       storybook: { type: 'boolean' },
+      e2e: { type: 'boolean' },
+      env: { type: 'boolean' },
+      canary: { type: 'boolean' },
       'pkg-checks': { type: 'boolean' },
       knip: { type: 'boolean' },
       jsr: { type: 'boolean' },
@@ -74,6 +78,9 @@ export function parseCliArgs(argv) {
   if (values.minify) overrides.minify = true;
   if (values.monorepo) overrides.monorepo = true;
   if (values.storybook) overrides.storybook = true;
+  if (values.e2e) overrides.e2e = true;
+  if (values.env) overrides.env = true;
+  if (values.canary) overrides.canary = true;
   if (values['pkg-checks']) overrides.pkgChecks = true;
   if (values.knip) overrides.knip = true;
   if (values.jsr) overrides.jsr = true;

package/src/cli/index.js

@@ -40,11 +40,13 @@ Options:
   --language <ts|js>  --module <esm|cjs|dual>  --framework <none|react|vue|svelte>
   --target <library|cli|service|app>   (repeatable)   --storybook
   --bundler <tsup|tsdown|unbuild|rollup|none>   --minify
-  --test <vitest|jest|node|none>  --lint <eslint-prettier|biome|oxlint|none>
+  --test <vitest|jest|node|none>   --e2e (Playwright, for apps)
+  --env (type-safe env validation, services/CLIs)   --no-sourcemaps
+  --lint <eslint-prettier|biome|oxlint|none>
   --hooks <simple-git-hooks|husky|lefthook|none>  --release <changesets|release-it|np|none>
   --workflows <ci|npm-publish|pages|codeql|codecov|stale>   (repeatable)
   --deps <renovate|dependabot|none>  --license <MIT|Apache-2.0|ISC|none>
-  --pkg-checks (publint + are-the-types-wrong)   --knip   --jsr
+  --pkg-checks (publint + are-the-types-wrong)   --knip   --jsr   --canary
   --no-coverage  --no-community  --no-agents  --no-vscode  --no-editorconfig
   --schema            Print the full option/preset schema as JSON (for tools/agents)
   -h, --help          Show this help

package/src/cli/wizard.js

@@ -36,9 +36,18 @@ export async function runWizard(seed = {}) {
     cfg.minify = bail(await p.confirm({ message: 'Minify the build output?', initialValue: false }));
   }
   cfg.test = bail(await p.select({ message: 'Test runner', options: asOptions('test'), initialValue: OPTIONS.test.default }));
+  if (cfg.target.includes('app')) {
+    cfg.e2e = bail(await p.confirm({ message: 'Add Playwright end-to-end tests?', initialValue: false }));
+  }
   cfg.lint = bail(await p.select({ message: 'Lint / format', options: asOptions('lint'), initialValue: OPTIONS.lint.default }));
   cfg.gitHooks = bail(await p.select({ message: 'Git hooks', options: asOptions('gitHooks'), initialValue: OPTIONS.gitHooks.default }));
+  if (cfg.target.includes('service') || cfg.target.includes('cli')) {
+    cfg.env = bail(await p.confirm({ message: 'Type-safe env validation (Zod)?', initialValue: false }));
+  }
   cfg.release = bail(await p.select({ message: 'Release / versioning', options: asOptions('release'), initialValue: OPTIONS.release.default }));
+  if (cfg.release === 'changesets') {
+    cfg.canary = bail(await p.confirm({ message: 'Add a canary/snapshot release workflow?', initialValue: false }));
+  }
   cfg.workflows = bail(await p.multiselect({ message: 'GitHub Actions (space to toggle)', options: asOptions('workflows'), initialValues: OPTIONS.workflows.default, required: false }));
   cfg.deps = bail(await p.select({ message: 'Dependency updates', options: asOptions('deps'), initialValue: OPTIONS.deps.default }));
   cfg.license = bail(await p.select({ message: 'License', options: asOptions('license'), initialValue: OPTIONS.license.default }));

package/src/core/features/bundler.js

@@ -18,6 +18,9 @@ export default {
       if (cfg.hasEsm) pkg.module = './src/index.js';
     } else {
       pkg.files = ['dist'];
+      // Ship source alongside dist so the JS sourcemaps resolve — consumers can
+      // step into and go-to-definition on your original code.
+      if (cfg.sourcemaps) pkg.files.push('src');
       const esm = './dist/index.js';
       const cjs = './dist/index.cjs';
       const dtsEsm = './dist/index.d.ts';

package/src/core/features/e2e.js

@@ -0,0 +1,47 @@
+// Playwright end-to-end tests for app targets: a config that boots the Vite
+// dev server, one smoke spec, the scripts and the dev dependency. The CI job
+// lives in workflows.js, which owns all workflow YAML.
+
+const DEV_URL = 'http://localhost:5173'; // Vite's default dev port
+
+const runDev = (cfg) => (cfg.packageManager === 'npm' ? 'npm run dev' : `${cfg.packageManager} dev`);
+
+export default {
+  id: 'e2e',
+  active: (cfg) => cfg.e2e && cfg.hasApp,
+  apply(cfg) {
+    const ext = cfg.ext; // 'ts' | 'js' — config/specs never need JSX
+    const files = {};
+    const pkg = { scripts: {}, devDependencies: { '@playwright/test': '^1.50.0' } };
+
+    files[`playwright.config.${ext}`] = [
+      `import { defineConfig, devices } from '@playwright/test';`,
+      ``,
+      `export default defineConfig({`,
+      `\ttestDir: './e2e',`,
+      `\tuse: { baseURL: '${DEV_URL}', trace: 'on-first-retry' },`,
+      `\t// Playwright starts the app for you and waits for it to be ready.`,
+      `\twebServer: {`,
+      `\t\tcommand: '${runDev(cfg)}',`,
+      `\t\turl: '${DEV_URL}',`,
+      `\t\treuseExistingServer: !process.env.CI,`,
+      `\t},`,
+      `\tprojects: [{ name: 'chromium', use: { ...devices['Desktop Chrome'] } }],`,
+      `});`,
+      ``,
+    ].join('\n');
+
+    files[`e2e/app.spec.${ext}`] = [
+      `import { test, expect } from '@playwright/test';`,
+      ``,
+      `test('renders the app', async ({ page }) => {`,
+      `\tawait page.goto('/');`,
+      `\tawait expect(page.getByRole('heading', { name: /Hello from/ })).toBeVisible();`,
+      `});`,
+      ``,
+    ].join('\n');
+
+    pkg.scripts['test:e2e'] = 'playwright test';
+    return { files, pkg };
+  },
+};

package/src/core/features/env.js

@@ -0,0 +1,58 @@
+// Type-safe environment-variable validation for server-side runtimes (services
+// and CLIs). Validates process.env once at startup with a Zod schema, so a
+// misconfigured deploy fails fast with a clear message instead of a surprise
+// runtime crash. Ships a matching .env.example.
+
+export default {
+  id: 'env',
+  active: (cfg) => cfg.env && (cfg.hasService || cfg.hasCli),
+  apply(cfg) {
+    const files = {};
+
+    files[`src/env.${cfg.ext}`] = cfg.isTs ? envTs() : envJs();
+    files['.env.example'] = ['NODE_ENV=development', 'PORT=3000', ''].join('\n');
+
+    return { files, pkg: { dependencies: { zod: '^4.0.0' } } };
+  },
+};
+
+function envTs() {
+  return [
+    `import { z } from 'zod';`,
+    ``,
+    `const schema = z.object({`,
+    `\tNODE_ENV: z.enum(['development', 'production', 'test']).default('development'),`,
+    `\tPORT: z.coerce.number().default(3000),`,
+    `});`,
+    ``,
+    `const parsed = schema.safeParse(process.env);`,
+    `if (!parsed.success) {`,
+    `\tconsole.error('❌ Invalid environment variables:', z.treeifyError(parsed.error));`,
+    `\tprocess.exit(1);`,
+    `}`,
+    ``,
+    `export const env = parsed.data;`,
+    ``,
+  ].join('\n');
+}
+
+function envJs() {
+  return [
+    `import { z } from 'zod';`,
+    ``,
+    `const schema = z.object({`,
+    `\tNODE_ENV: z.enum(['development', 'production', 'test']).default('development'),`,
+    `\tPORT: z.coerce.number().default(3000),`,
+    `});`,
+    ``,
+    `const parsed = schema.safeParse(process.env);`,
+    `if (!parsed.success) {`,
+    `\tconsole.error('❌ Invalid environment variables:', z.treeifyError(parsed.error));`,
+    `\tprocess.exit(1);`,
+    `}`,
+    ``,
+    `/** @type {z.infer<typeof schema>} */`,
+    `export const env = parsed.data;`,
+    ``,
+  ].join('\n');
+}

package/src/core/features/gitfiles.js

@@ -10,6 +10,11 @@ dist/
 coverage/
 *.tsbuildinfo
 
+# test artifacts (Playwright)
+test-results/
+playwright-report/
+playwright/.cache/
+
 # logs
 *.log
 npm-debug.log*

package/src/core/features/index.js

@@ -7,7 +7,9 @@ import typescript from './typescript.js';
 import frameworks from './frameworks.js';
 import vite from './vite.js';
 import service from './service.js';
+import env from './env.js';
 import test from './test.js';
+import e2e from './e2e.js';
 import lint from './lint.js';
 import githooks from './githooks.js';
 import release from './release.js';
@@ -28,7 +30,9 @@ export default [
   frameworks,
   vite,
   service,
+  env,
   test,
+  e2e,
   lint,
   githooks,
   release,

package/src/core/features/service.js

@@ -10,7 +10,7 @@ export default {
       [`src/app.${ext}`]: appFile(cfg),
       [`src/index.${ext}`]: serverFile(cfg),
       Dockerfile: dockerfile(cfg),
-      '.dockerignore': 'node_modules\ndist\n.git\n.env\n',
+      '.dockerignore': ['node_modules', 'dist', 'coverage', '.git', '.github', '.env', '.env.*', '!.env.example', '*.log', 'Dockerfile', '.dockerignore', ''].join('\n'),
     };
     return {
       files,
@@ -43,22 +43,25 @@ function appFile(cfg) {
 function serverFile(cfg) {
   return [
     `import { serve } from '@hono/node-server';`,
-    `import { app } from './app${cfg.isTs ? '.js' : '.js'}';`,
+    `import { app } from './app.js';`,
+    cfg.env ? `import { env } from './env.js';` : null,
     ``,
-    `const port = Number(process.env.PORT) || 3000;`,
+    `const port = ${cfg.env ? 'env.PORT' : 'Number(process.env.PORT) || 3000'};`,
     `serve({ fetch: app.fetch, port }, (info) => {`,
     `\tconsole.log(\`Listening on http://localhost:\${info.port}\`);`,
     `});`,
     ``,
-  ].join('\n');
+  ].filter((l) => l !== null).join('\n');
 }
 
 function dockerfile(cfg) {
   const node = cfg.nodeVersion;
   const pm = cfg.packageManager;
   const install = pm === 'npm' ? 'npm ci' : `${pm} install --frozen-lockfile`;
+  const prune = pm === 'npm' ? 'npm ci --omit=dev' : `${pm} install --prod --frozen-lockfile`;
   const build = pm === 'npm' ? 'npm run build' : `${pm} run build`;
   return [
+    `# --- build stage: install everything and compile ---`,
     `FROM node:${node}-slim AS build`,
     `WORKDIR /app`,
     `COPY package*.json ./`,
@@ -66,13 +69,22 @@ function dockerfile(cfg) {
     `COPY . .`,
     `RUN ${build}`,
     ``,
+    `# --- deps stage: production-only node_modules for a smaller image ---`,
+    `FROM node:${node}-slim AS deps`,
+    `WORKDIR /app`,
+    `COPY package*.json ./`,
+    `RUN ${prune}`,
+    ``,
+    `# --- runtime stage: slim, non-root, healthchecked ---`,
     `FROM node:${node}-slim`,
     `WORKDIR /app`,
     `ENV NODE_ENV=production`,
-    `COPY --from=build /app/node_modules ./node_modules`,
+    `COPY --from=deps /app/node_modules ./node_modules`,
     `COPY --from=build /app/dist ./dist`,
     `COPY package.json ./`,
+    `USER node`,
     `EXPOSE 3000`,
+    `HEALTHCHECK --interval=30s --timeout=3s CMD node -e "fetch('http://localhost:'+(process.env.PORT||3000)+'/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"`,
     `CMD ["node", "dist/index.js"]`,
     ``,
   ].join('\n');

package/src/core/features/test.js

@@ -26,6 +26,9 @@ export default {
         `export default defineConfig({`,
         fw ? `\tplugins: [${fw.call}],` : null,
         `\ttest: {`,
+        // Keep Vitest to unit tests under src/ so it never tries to run the
+        // Playwright specs in e2e/ (they share the *.spec.ts glob).
+        cfg.e2e ? `\t\tinclude: ['src/**/*.{test,spec}.{js,jsx,ts,tsx}'],` : null,
         cfg.hasFramework ? `\t\tenvironment: 'jsdom',` : null,
         cfg.hasFramework ? `\t\tglobals: true,` : null,
         cfg.coverage ? `\t\tcoverage: { provider: 'v8', reporter: ['text', 'lcov'] },` : null,

package/src/core/features/typescript.js

@@ -19,6 +19,9 @@ export default {
       forceConsistentCasingInFileNames: true,
       verbatimModuleSyntax: cfg.bundler !== 'none' && !cfg.hasFramework,
       declaration: true,
+      // Declaration maps let editors jump from the published .d.ts into the
+      // shipped .ts source (the bundler emits JS sourcemaps to match).
+      ...(cfg.sourcemaps ? { declarationMap: true } : {}),
     };
     if (noBuild) {
       // tsc is the build: emit to dist.
@@ -26,6 +29,7 @@ export default {
       compilerOptions.module = 'NodeNext';
       compilerOptions.outDir = 'dist';
       compilerOptions.rootDir = 'src';
+      if (cfg.sourcemaps) compilerOptions.sourceMap = true;
     } else {
       compilerOptions.noEmit = true;
     }

package/src/core/features/workflows.js

@@ -12,6 +12,10 @@ function pmInstall(cfg) {
 function pmRun(cfg, script) {
   return cfg.packageManager === 'npm' ? `npm run ${script}` : `${cfg.packageManager} ${script}`;
 }
+// Run a package binary (not an npm script) with the right runner per pm.
+function pmExec(cfg, cmd) {
+  return { npm: `npx ${cmd}`, pnpm: `pnpm exec ${cmd}`, yarn: `yarn ${cmd}`, bun: `bunx ${cmd}` }[cfg.packageManager];
+}
 function setupSteps(cfg) {
   const steps = ['      - uses: actions/checkout@v4'];
   if (cfg.packageManager === 'pnpm') steps.push('      - uses: pnpm/action-setup@v4');
@@ -41,6 +45,8 @@ export default {
     if (wf.includes('pages')) files['.github/workflows/pages.yml'] = pagesWorkflow(cfg);
     if (wf.includes('codeql')) files['.github/workflows/codeql.yml'] = codeqlWorkflow();
     if (wf.includes('stale')) files['.github/workflows/stale.yml'] = staleWorkflow();
+    if (cfg.e2e && cfg.hasApp && wf.includes('ci')) files['.github/workflows/e2e.yml'] = e2eWorkflow(cfg);
+    if (cfg.canary && cfg.release === 'changesets') files['.github/workflows/canary.yml'] = canaryWorkflow(cfg);
 
     if (cfg.deps === 'renovate') {
       files['.github/renovate.json'] = toJson({
@@ -199,6 +205,54 @@ function codeqlWorkflow() {
   ].join('\n');
 }
 
+function e2eWorkflow(cfg) {
+  return [
+    'name: E2E',
+    'on:',
+    '  push:',
+    '    branches: [main]',
+    '  pull_request:',
+    'jobs:',
+    '  e2e:',
+    '    runs-on: ubuntu-latest',
+    '    steps:',
+    setupSteps(cfg),
+    '      - run: npx playwright install --with-deps chromium',
+    `      - run: ${pmRun(cfg, 'test:e2e')}`,
+    '      - uses: actions/upload-artifact@v4',
+    '        if: ${{ !cancelled() }}',
+    '        with:',
+    '          name: playwright-report',
+    '          path: playwright-report/',
+    '          retention-days: 7',
+    '',
+  ].join('\n');
+}
+
+function canaryWorkflow(cfg) {
+  return [
+    'name: Canary',
+    '# Manually publish a snapshot (x.y.z-canary-<hash>) to the `canary` dist-tag',
+    '# so consumers can test unreleased changes: npm i ' + cfg.name + '@canary',
+    'on:',
+    '  workflow_dispatch:',
+    'concurrency: canary-${{ github.ref }}',
+    'permissions:',
+    '  contents: read',
+    'jobs:',
+    '  canary:',
+    '    runs-on: ubuntu-latest',
+    '    steps:',
+    setupSteps(cfg),
+    '      - name: Authenticate with npm',
+    '        run: echo "//registry.npmjs.org/:_authToken=${{ secrets.NPM_TOKEN }}" >> ~/.npmrc',
+    `      - run: ${pmExec(cfg, 'changeset version --snapshot canary')}`,
+    cfg.hasBuild ? `      - run: ${pmRun(cfg, 'build')}` : null,
+    `      - run: ${pmExec(cfg, 'changeset publish --no-git-tag --tag canary')}`,
+    '',
+  ].filter((l) => l !== null).join('\n');
+}
+
 function staleWorkflow() {
   return [
     'name: Stale',

package/src/core/options.js

@@ -96,6 +96,10 @@ export const OPTIONS = {
   },
   coverage: { group: 'quality', type: 'boolean', label: 'Coverage reporting', default: true },
   storybook: { group: 'quality', type: 'boolean', label: 'Storybook (component libraries)', default: false },
+  e2e: { group: 'quality', type: 'boolean', label: 'Playwright end-to-end tests (apps)', default: false },
+  sourcemaps: { group: 'build', type: 'boolean', label: 'Sourcemaps + ship source (debug into original code)', default: true },
+  env: { group: 'quality', type: 'boolean', label: 'Type-safe env validation (Zod) — services & CLIs', default: false },
+  canary: { group: 'release', type: 'boolean', label: 'Snapshot / canary release workflow (Changesets)', default: false },
   pkgChecks: { group: 'quality', type: 'boolean', label: 'Package checks (publint + are-the-types-wrong)', default: false },
   knip: { group: 'quality', type: 'boolean', label: 'Knip (unused files / deps / exports)', default: false },
 
@@ -245,12 +249,21 @@ export function normalizeConfig(input = {}) {
   // Storybook only applies to component libraries.
   if (!cfg.hasFramework || cfg.hasApp || !cfg.hasLibrary) cfg.storybook = false;
 
+  // Playwright E2E only applies to app targets.
+  if (!cfg.hasApp) cfg.e2e = false;
+
   // A monorepo is its own generation path (see buildMonorepo); it has a build.
   if (cfg.monorepo) cfg.hasBuild = true;
 
   cfg.publishable = (cfg.hasLibrary || cfg.hasCli) && !cfg.hasApp && !cfg.hasService;
   // Package-correctness checks only make sense for a publishable package.
   if (!cfg.publishable) cfg.pkgChecks = false;
+  // Sourcemaps + shipped source only matter for a published package.
+  if (!cfg.publishable) cfg.sourcemaps = false;
+  // Env validation is for server-side runtimes (services / CLIs), not libs/apps.
+  if (!(cfg.hasService || cfg.hasCli)) cfg.env = false;
+  // Canary snapshots ride on the Changesets flow.
+  if (cfg.release !== 'changesets') cfg.canary = false;
   // JSR is TypeScript-first, ESM, and for plain (non-framework) libraries.
   if (!(cfg.isTs && cfg.hasLibrary && !cfg.hasFramework && !cfg.hasApp)) cfg.jsr = false;
   return cfg;