create-packkit 2.1.0 → 2.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-packkit",
-  "version": "2.1.0",
+  "version": "2.3.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',
@@ -49,8 +50,11 @@ export function parseCliArgs(argv) {
       monorepo: { type: 'boolean' },
       storybook: { type: 'boolean' },
       e2e: { type: 'boolean' },
+      env: { type: 'boolean' },
+      canary: { type: 'boolean' },
       'pkg-checks': { type: 'boolean' },
       knip: { type: 'boolean' },
+      'size-limit': { type: 'boolean' },
       jsr: { type: 'boolean' },
       help: { type: 'boolean', short: 'h' },
       version: { type: 'boolean', short: 'v' },
@@ -76,8 +80,11 @@ export function parseCliArgs(argv) {
   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['size-limit']) overrides.sizeLimit = true;
   if (values.jsr) overrides.jsr = true;
   for (const [flag, key] of Object.entries(NEGATABLE)) {
     if (values[flag]) overrides[key] = false;

package/src/cli/index.js

@@ -41,11 +41,13 @@ Options:
   --target <library|cli|service|app>   (repeatable)   --storybook
   --bundler <tsup|tsdown|unbuild|rollup|none>   --minify
   --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
+  --size-limit (bundle-size budget, libraries)
   --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

@@ -41,7 +41,13 @@ export async function runWizard(seed = {}) {
   }
   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/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/index.js

@@ -7,6 +7,7 @@ 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';
@@ -14,6 +15,7 @@ import githooks from './githooks.js';
 import release from './release.js';
 import cli from './cli.js';
 import checks from './checks.js';
+import sizelimit from './sizelimit.js';
 import jsr from './jsr.js';
 import workflows from './workflows.js';
 import storybook from './storybook.js';
@@ -29,6 +31,7 @@ export default [
   frameworks,
   vite,
   service,
+  env,
   test,
   e2e,
   lint,
@@ -36,6 +39,7 @@ export default [
   release,
   cli,
   checks,
+  sizelimit,
   jsr,
   workflows,
   storybook,

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/sizelimit.js

@@ -0,0 +1,23 @@
+// size-limit: a bundle-size budget for published libraries. Measures the
+// brotli-compressed size of the built entry and fails when it exceeds the
+// limit — cheap insurance against a dependency silently bloating the package.
+import { toJson } from '../render.js';
+
+export default {
+  id: 'sizelimit',
+  active: (cfg) => cfg.sizeLimit,
+  apply(cfg) {
+    return {
+      files: {
+        '.size-limit.json': toJson([{ name: cfg.name, path: 'dist/index.js', limit: '10 kB' }]),
+      },
+      pkg: {
+        scripts: { size: 'size-limit' },
+        devDependencies: {
+          'size-limit': '^11.0.0',
+          '@size-limit/preset-small-lib': '^11.0.0',
+        },
+      },
+    };
+  },
+};

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');
@@ -42,6 +46,7 @@ export default {
     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({
@@ -75,6 +80,7 @@ function ciWorkflow(cfg, codecov) {
   if (cfg.test !== 'none') jobs.push(`      - run: ${pmRun(cfg, codecov ? 'coverage' : 'test')}`);
   if (cfg.knip) jobs.push(`      - run: ${pmRun(cfg, 'knip')}`);
   if (cfg.hasBuild) jobs.push(`      - run: ${pmRun(cfg, 'build')}`);
+  if (cfg.sizeLimit) jobs.push(`      - run: ${pmRun(cfg, 'size')}`); // after build (measures dist)
   if (cfg.pkgChecks) jobs.push(`      - run: ${pmRun(cfg, 'check:pkg')}`); // after build (attw packs dist)
   const cov = codecov
     ? '\n      - uses: codecov/codecov-action@v4\n        with:\n          token: ${{ secrets.CODECOV_TOKEN }}'
@@ -224,6 +230,30 @@ function e2eWorkflow(cfg) {
   ].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

@@ -97,8 +97,12 @@ 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 },
+  sizeLimit: { group: 'quality', type: 'boolean', label: 'size-limit (bundle-size budget, libraries)', default: false },
 
   // ---- lint / format ----
   lint: {
@@ -255,6 +259,14 @@ export function normalizeConfig(input = {}) {
   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;
+  // A bundle-size budget needs a published package with a built entry.
+  if (!(cfg.publishable && cfg.hasBuild)) cfg.sizeLimit = 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;