create-stator 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tony Sullivan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/index.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+// Minimal Stator scaffolder: copies the embedded template into a new
+// directory and stamps the project name. No prompts, no network.
+import { cp, readdir, readFile, rename, stat, writeFile } from 'node:fs/promises'
+import { basename, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const target = process.argv[2]
+if (!target) {
+  console.log('Usage: pnpm create stator <directory>')
+  console.log('       npm create stator@latest <directory>')
+  process.exit(1)
+}
+
+const dest = resolve(process.cwd(), target)
+try {
+  const existing = await readdir(dest)
+  if (existing.length > 0) {
+    console.error(`create-stator: ${target} exists and is not empty — refusing to overwrite.`)
+    process.exit(1)
+  }
+} catch {
+  // does not exist — fine
+}
+
+const templateDir = fileURLToPath(new URL('./template', import.meta.url))
+await cp(templateDir, dest, { recursive: true })
+
+// npm strips dotfiles from published packages; ship as _gitignore and rename.
+try {
+  await stat(join(dest, '_gitignore'))
+  await rename(join(dest, '_gitignore'), join(dest, '.gitignore'))
+} catch {
+  // already named .gitignore (running from the repo)
+}
+
+const name = basename(dest)
+  .toLowerCase()
+  .replace(/[^a-z0-9-]/g, '-')
+const pkgPath = join(dest, 'package.json')
+const pkg = JSON.parse(await readFile(pkgPath, 'utf8'))
+pkg.name = name
+await writeFile(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`)
+
+console.log(`
+  Scaffolded ${name} into ${dest}
+
+  Next steps:
+    cd ${target}
+    pnpm install
+    pnpm dev        # http://localhost:3000
+
+  Other scripts: pnpm typecheck · pnpm build · pnpm start
+`)

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "create-stator",
+  "version": "1.0.0",
+  "description": "Scaffold a new Stator app: pnpm create stator my-app",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "create-stator": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "template"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/statorjs/stator.git",
+    "directory": "packages/create-stator"
+  },
+  "homepage": "https://github.com/statorjs/stator#readme",
+  "engines": {
+    "node": ">=20"
+  }
+}

package/template/_gitignore

@@ -0,0 +1,3 @@
+node_modules/
+dist/
+.stator/

package/template/build.ts

@@ -0,0 +1,7 @@
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { buildApp } from '@statorjs/stator/build'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const result = await buildApp({ root: here, outDir: resolve(here, 'dist') })
+console.log(`stator: built ${result.compiled} components → ${result.outDir}`)

package/template/machines/counter.ts

@@ -0,0 +1,27 @@
+import { defineMachine } from '@statorjs/stator/server'
+
+type Events = { type: 'INCREMENT' } | { type: 'RESET' }
+
+export default defineMachine({
+  name: 'CounterMachine',
+  lifecycle: 'session',
+  events: {} as Events,
+  context: { count: 0 },
+  initial: 'idle',
+  states: {
+    idle: {
+      on: {
+        INCREMENT: (ctx) => {
+          ctx.count += 1
+        },
+        RESET: (ctx) => {
+          ctx.count = 0
+        },
+      },
+    },
+  },
+  selectors: {
+    count: (ctx) => ctx.count,
+    label: (ctx) => `count is ${ctx.count}`,
+  },
+})

package/template/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "my-stator-app",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "sync": "tsx sync.ts",
+    "typecheck": "tsx sync.ts && tsc --noEmit",
+    "dev": "tsx watch server.ts",
+    "build": "tsx build.ts",
+    "start": "tsx start.ts"
+  },
+  "dependencies": {
+    "@statorjs/stator": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.7.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0",
+    "vite": "^6.0.0",
+    "pino-pretty": "^13.1.3"
+  }
+}

package/template/routes/index.stator

@@ -0,0 +1,14 @@
+---
+import Counter from '../machines/counter.ts'
+import Layout from '../templates/layout.stator'
+
+const [counter] = Stator.reads([Counter])
+---
+<Layout>
+  <section class="counter">
+    <h1>Hello, Stator</h1>
+    <p class="count">{read(counter, (c) => c.label)}</p>
+    <button on:click={() => counter.send({ type: 'INCREMENT' })}>+1</button>
+    <button on:click={() => counter.send({ type: 'RESET' })}>reset</button>
+  </section>
+</Layout>

package/template/server.ts

@@ -0,0 +1,19 @@
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { createDevApp } from '@statorjs/stator/dev'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const port = Number(process.env.PORT ?? 3000)
+
+// Dev server: Vite compiles `.stator` on the way in, with live reload and the
+// inspector toolbar. Production runs `pnpm build && pnpm start` instead.
+// Sessions default to the in-memory store — swap in RedisStore (from
+// '@statorjs/stator/server') to survive restarts.
+const app = await createDevApp({
+  root: here,
+  machinesDir: resolve(here, 'machines'),
+  routesDir: resolve(here, 'routes'),
+  staticDir: resolve(here, 'static'),
+})
+
+await app.listen(port)

package/template/start.ts

@@ -0,0 +1,25 @@
+import { stat } from 'node:fs/promises'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { loadProductionHead } from '@statorjs/stator/build'
+import { createApp, logger } from '@statorjs/stator/server'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const dist = resolve(here, 'dist')
+const port = Number(process.env.PORT ?? 3000)
+
+try {
+  await stat(resolve(dist, 'routes'))
+} catch {
+  logger.error({}, 'no dist/ found — run `pnpm build` first')
+  process.exit(1)
+}
+
+const app = await createApp({
+  machinesDir: resolve(dist, 'machines'),
+  routesDir: resolve(dist, 'routes'),
+  staticDir: resolve(dist, 'static'),
+  headExtras: await loadProductionHead(dist),
+})
+
+await app.listen(port)

package/template/static/app.css

@@ -0,0 +1,5 @@
+:root { font-family: system-ui, sans-serif; color-scheme: light dark; }
+body { margin: 0; display: grid; place-items: center; min-height: 100vh; }
+.counter { text-align: center; }
+.count { font-size: 1.5rem; font-variant-numeric: tabular-nums; }
+button { font: inherit; padding: 0.4rem 1rem; margin: 0 0.25rem; cursor: pointer; }

package/template/stator-env.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Ambient type for `.stator` single-file components, for this app's TypeScript
+ * project. (Stator apps include one of these, like Vite apps include env.d.ts.)
+ */
+declare module '*.stator' {
+  import type { HtmlFragment } from '@statorjs/stator/template'
+
+  // biome-ignore lint/suspicious/noExplicitAny: the wildcard fallback must admit every component's props — `Record<string, unknown>` would reject interfaces without index signatures
+  const component: (props?: any) => HtmlFragment
+  export default component
+}

package/template/sync.ts

@@ -0,0 +1,7 @@
+import { dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { syncTypes } from '@statorjs/stator/build'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const { written } = await syncTypes(here)
+console.log(`stator: wrote ${written} .stator.d.ts files`)

package/template/templates/layout.stator

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>stator app</title>
+    <link rel="stylesheet" href="/static/app.css" />
+  </head>
+  <body>
+    <main><children /></main>
+  </body>
+</html>

package/template/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2022", "DOM"],
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "isolatedModules": true,
+    "allowImportingTsExtensions": true,
+    "noEmit": true,
+    "rootDirs": [".", ".stator/types"]
+  },
+  "include": ["**/*.ts"],
+  "exclude": ["node_modules", "static", "dist"]
+}