@webjsdev/cli 0.10.32 → 0.10.34

package/lib/create.js

@@ -49,6 +49,27 @@ function runInstall(appDir, pm) {
   return r.status === 0;
 }
 
+/**
+ * Author the INITIAL Drizzle migration for the shipped schema, so the app boots
+ * with its tables and the very first `run dev` works with no manual step. The
+ * scaffold's schema is TypeScript (`db/schema.server.ts`); `db migrate` (run in
+ * `webjs.dev.before` / `webjs.start.before`) only applies migration SQL FILES, so
+ * with no file the shipped example hits "no such table". `db generate` turns the
+ * schema into that first `db/migrations/*.sql`. It runs OFFLINE (a schema-to-SQL
+ * diff, no database connection), so it is safe for sqlite AND postgres here, well
+ * before any `DATABASE_URL` exists. Needs `drizzle-kit`, so it only runs after a
+ * successful install; on `--no-install` the printed next-steps still show
+ * `db:generate`. Returns whether a migration was authored.
+ *
+ * @param {string} appDir
+ * @param {string} pm
+ * @returns {boolean}
+ */
+function runDbGenerate(appDir, pm) {
+  const r = spawnSync(pm, ['run', 'db:generate'], { cwd: appDir, stdio: 'inherit' });
+  return r.status === 0;
+}
+
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const TEMPLATES = resolve(__dirname, '..', 'templates');
 
@@ -521,9 +542,12 @@ export async function scaffoldApp(name, cwd, opts = {}) {
     // Environment variables
     '.env.example',
     // Project-level gitignore (node_modules, .webjs, .env, OS junk).
-    // The SQLite dev.db rule is appended programmatically below so it
-    // only appears for the sqlite dialect.
-    '.gitignore',
+    // Shipped as `gitignore` (no dot) and renamed to `.gitignore` on copy:
+    // npm STRIPS a `.gitignore` from a published tarball, so a dotfile name
+    // would arrive missing and the app would ship without a `.env` ignore
+    // (dogfood #845). The SQLite dev.db rule is appended programmatically
+    // below so it only appears for the sqlite dialect.
+    'gitignore',
     // Git hooks (blocks commits on main)
     '.hooks/pre-commit',
     // Claude Code config + hooks
@@ -596,14 +620,17 @@ export async function scaffoldApp(name, cwd, opts = {}) {
   for (const f of templateFiles) {
     const src = join(TEMPLATES, f);
     if (existsSync(src)) {
-      await mkdir(dirname(join(appDir, f)), { recursive: true });
+      // `gitignore` ships without a dot (npm strips a published `.gitignore`)
+      // and is written to `.gitignore` in the generated app.
+      const dest = f === 'gitignore' ? '.gitignore' : f;
+      await mkdir(dirname(join(appDir, dest)), { recursive: true });
       let content = await readFile(src, 'utf8');
       content = content.replace(/\{\{APP_NAME\}\}/g, name);
       if (isBun) {
         if (PROSE_REWRITE.has(f)) content = bunifyProse(content);
         else if (FILE_REWRITE[f]) content = FILE_REWRITE[f](content);
       }
-      await writeFile(join(appDir, f), content);
+      await writeFile(join(appDir, dest), content);
     }
   }
 
@@ -816,7 +843,9 @@ export default defineConfig({
       const cur = await readFile(gitignore, 'utf8');
       if (!cur.includes('db/dev.db')) await writeFile(gitignore, cur + gitignoreExtra);
     } else {
-      await writeFile(gitignore, 'node_modules\n.webjs\n' + gitignoreExtra);
+      // Defense in depth: if the template gitignore is ever absent, still
+      // never leave a real `.env` trackable (dogfood #845).
+      await writeFile(gitignore, 'node_modules\n.webjs\n.env\n.env.*\n!.env.example\n' + gitignoreExtra);
     }
   }
 
@@ -1072,6 +1101,15 @@ export default function RootLayout({ children }: { children: unknown }) {
   const nonce = cspNonce();
   return html\`
     <script nonce="\${nonce}">
+      // ===== OPTIONAL: light/dark theme apparatus (remove as one unit) =====
+      // This IIFE reads the saved or OS theme and toggles the data-theme
+      // attribute plus the dark class the ui kit reads, so the token VALUES in
+      // the root, dark, and data-theme style blocks below switch. It is what
+      // makes the app theme-aware. Building a SINGLE-theme app of your own?
+      // Delete this IIFE, delete the dark and light style blocks below, and set
+      // your palette once on the root selector. That removes the wiring so it
+      // cannot fight your own colours (it will not override a plain root
+      // palette). The header-measure IIFE that follows is unrelated, keep it.
       (function(){
         try {
           var mq = window.matchMedia('(prefers-color-scheme: light)');
@@ -1091,6 +1129,7 @@ export default function RootLayout({ children }: { children: unknown }) {
           mq.addEventListener('change', apply);
         } catch (_) {}
       })();
+      // ===== end optional theme apparatus =====
       // The header is position:fixed (not sticky): a sticky header flickers on
       // iOS WebKit during a client-router nav. fixed leaves normal flow, so
       // --header-h reserves its height for the content below. Measured here so
@@ -1676,11 +1715,21 @@ For AI agents, read this before editing scaffolded files:
   // (#541). Otherwise honour the invoking PM (npm / pnpm / yarn / bun).
   const pm = isBun ? 'bun' : detectPackageManager();
   let installed = false;
+  let generatedMigration = false;
   if (shouldInstall) {
     console.log(`Running '${pm} install' in ${name}/ ...\n`);
     installed = runInstall(appDir, pm);
     if (!installed) {
       console.log(`\n[warn] ${pm} install failed. Run '${pm} install' manually in ${name}/ to finish setup.\n`);
+    } else {
+      // Author the initial migration NOW (drizzle-kit is installed), so the
+      // shipped schema's tables exist and the very first `run dev` works with no
+      // manual step (webjs.*.before applies the migration on boot). See runDbGenerate.
+      console.log(`Authoring the initial database migration ('${pm} run db:generate') ...\n`);
+      generatedMigration = runDbGenerate(appDir, pm);
+      if (!generatedMigration) {
+        console.log(`\n[warn] '${pm} run db:generate' failed. Run it manually in ${name}/ before '${pm} run dev'.\n`);
+      }
     }
   }
 
@@ -1691,14 +1740,14 @@ For AI agents, read this before editing scaffolded files:
   // templates ship with @webjsdev/ui already initialised; the api
   // template has no UI but may add one later.
   const installSegment = installed ? '' : `${pm} install && `;
-  // Some examples query the db on their first request, so a migration must be
-  // authored first: `db:generate` writes it and the `webjs.dev.before` migrate
-  // applies it on `run dev` (Drizzle splits Prisma's `migrate dev` into
-  // generate-then-migrate). The saas example queries users (auth); the
-  // full-stack scaffold ships the gallery's /examples/todo route (queries todos).
-  // The api template has no such first-request query, so it boots with just
-  // `run dev`; once you add a db route, `db:generate` then `run dev` is the loop.
-  const dbSegment = isApi ? '' : `${pm} run db:generate && `;
+  // The shipped schema is applied on the first `run dev` (webjs.*.before runs
+  // `db migrate`), but only if a migration FILE exists. When we installed, we
+  // already authored it above (runDbGenerate), so the run command is just
+  // `run dev`. Otherwise (--no-install, or generate failed) the user authors it
+  // first: `db:generate` writes the migration from db/schema.server.ts, then
+  // `run dev` applies it (Drizzle splits Prisma's `migrate dev` into
+  // generate-then-migrate).
+  const dbSegment = generatedMigration ? '' : `${pm} run db:generate && `;
   const runCommand = `cd ${name} && ${installSegment}${dbSegment}${pm} run dev`;
   // Postgres needs a reachable DATABASE_URL before any migrate (sqlite uses a
   // local file with no .env). Point it at a running database; `dev` / `start`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/cli",
-  "version": "0.10.32",
+  "version": "0.10.34",
   "type": "module",
   "description": "webjs CLI - dev, start, create, db",
   "bin": {

package/templates/AGENTS.md

@@ -549,6 +549,7 @@ Scripts (all wrap `drizzle-kit`):
 - `npm run db:studio`: `webjs db studio` (visual DB browser)
 - `npm run db:seed`: `webjs db seed` (run `db/seed.server.ts`)
 - `webjs.dev.before` and `webjs.start.before` both run `webjs db migrate` inside `webjs dev` / `webjs start` (idempotent; replaces the old `prestart` hook), so after you `db:generate` a migration it is applied on the next boot with no manual `db:migrate` step.
+- The INITIAL migration for the shipped schema is authored by `webjs create` at setup time (right after install), so `db/migrations/` is populated and the first `run dev` works with no manual database step. You run `db:generate` yourself only when you CHANGE `db/schema.server.ts` (a new table or column), then the next `run dev` applies it.
 
 Always import `db` from `db/connection.server.ts` (the globalThis-cached
 singleton avoids opening a new connection on every dev-server reload), and

package/templates/CONVENTIONS.md

@@ -928,7 +928,11 @@ global light-DOM namespace.
 
 Every page wraps its output in `<div class="page-<route>">`. Every
 layout wraps in `<div class="layout-<name>">`. Components scope via
-their tag. Styles colocate as `const STYLES = css\`…\`` + `<style>${'$'}{STYLES.text}</style>`.
+their tag. In a PAGE or LAYOUT (which render server-only and never
+hydrate) styles colocate as `const STYLES = css\`…\`` + `<style>${'$'}{STYLES.text}</style>`.
+In a COMPONENT, do NOT interpolate into `<style>` (the client drops the
+raw-text hole on hydrate, so the styles vanish); use `static styles =
+css\`…\`` or Tailwind classes instead.
 
 ```ts
 // app/dashboard/page.ts

package/templates/gitignore

@@ -0,0 +1,68 @@
+# deps
+node_modules/
+
+# webjs / framework caches.
+# `.webjs/routes.d.ts` (the generated route-types overlay, regenerated per
+# machine by `webjs types` / `webjs dev`) is correctly ignored by `**/.webjs/*`.
+# `.webjs/vendor/` is the EXCEPTION: it holds the committed importmap
+# manifest (.webjs/vendor/importmap.json) and optionally the vendored
+# bundle files (after `webjs vendor pin --download`). Both ship to
+# production via source control so the server doesn't need
+# api.jspm.io reachable at boot. Pattern is `**/.webjs/*` ignored,
+# `.webjs/vendor/` un-ignored, mirroring Rails' config/importmap.rb
+# + vendor/javascript/ being committed.
+#
+# DO NOT "simplify" the three lines below to `.webjs/`. Git's
+# gitignore semantics excludes the parent first; once the parent is
+# excluded, no `!**/.webjs/vendor/` negation can ever re-include children
+# (the failure is silent: `webjs vendor pin` runs, writes files, and
+# git ignores them with no warning). The `gitignore-vendor-not-ignored`
+# lint rule (run via `webjs check`) verifies this with
+# `git check-ignore` and will fail CI if the pattern regresses.
+#
+# The `**/` prefix matches `.webjs/` at ANY depth, not just this app's
+# root. A slash-bearing `.webjs/*` anchors to this file's directory, so
+# an app nested below its repo root (a monorepo package) would leak its
+# generated `.webjs/routes.d.ts` into `git status`. `**/.webjs/*` covers
+# the nested case while the negations still re-include vendor at each
+# depth (a re-included parent dir permits a child negation).
+**/.webjs/*
+!**/.webjs/vendor/
+!**/.webjs/vendor/**
+
+# generated Tailwind CSS, built from public/input.css via npm run dev / start
+public/tailwind.css
+
+# env (.env.example stays tracked; the real .env never is)
+.env
+.env.*
+!.env.example
+
+# logs
+*.log
+npm-debug.log*
+
+# OS
+.DS_Store
+Thumbs.db
+
+# editors
+# `.vscode/*` ignored, but `.vscode/settings.json` (the webjs-config JSON
+# Schema association, #259) is committed so the editor validates package.json's
+# webjs block out of the box. Same gitignore shape as `.webjs/*` above: a bare
+# `.vscode/` would exclude the directory and no negation could re-include a
+# child, so the settings file would silently never ship.
+.vscode/*
+!.vscode/settings.json
+.idea/
+
+# test artifacts
+coverage/
+
+# AI assistants: local session state, scheduled-task locks, etc.
+# Repo-shared config (settings.json + hooks scripts) stays tracked so
+# every contributor and agent gets the same PreToolUse rules.
+.claude/*
+!.claude/settings.json
+!.claude/hooks/
+!.claude/hooks/**