@jasonshimmy/vite-plugin-cer-app 0.1.5 → 0.1.6

package/CHANGELOG.md

@@ -1,6 +1,10 @@
 # Changelog
 
 All notable changes to this project will be documented in this file.
+## [v0.1.6] - 2026-03-20
+
+- fix: update CLI usage instructions to include --package flag for create-cer-app (457114d)
+
 ## [v0.1.5] - 2026-03-20
 
 - fix: use vite plugin for light dom jit css fix: update incorrect docs fix: fix the plugin config (c32cf6a)

package/README.md

@@ -58,17 +58,20 @@ export default defineConfig({
 The fastest path is scaffolding a new project:
 
 ```sh
-npx create-cer-app my-app
+npx --package @jasonshimmy/vite-plugin-cer-app create-cer-app my-app
 # → choose spa / ssr / ssg
 cd my-app
 npm install
 npm run dev
 ```
 
-Or install the CLI globally:
+> **Note:** The `--package` flag is required because `create-cer-app` is bundled inside `@jasonshimmy/vite-plugin-cer-app` rather than published as a standalone package.
+
+Or install the CLI globally to skip the flag entirely:
 
 ```sh
 npm install -g @jasonshimmy/vite-plugin-cer-app
+create-cer-app my-app
 cer-app dev
 ```
 

package/commits.txt

@@ -1 +1 @@
-- fix: use vite plugin for light dom jit css fix: update incorrect docs fix: fix the plugin config (c32cf6a)
+- fix: update CLI usage instructions to include --package flag for create-cer-app (457114d)

package/dist/cli/create/templates/spa/app/app.ts.tpl

@@ -0,0 +1,93 @@
+import '@jasonshimmy/custom-elements-runtime/css'
+import 'virtual:cer-jit-css'
+import 'virtual:cer-components'
+import routes from 'virtual:cer-routes'
+import layouts from 'virtual:cer-layouts'
+import plugins from 'virtual:cer-plugins'
+import { hasLoading, loadingTag } from 'virtual:cer-loading'
+import { hasError, errorTag } from 'virtual:cer-error'
+import {
+  component,
+  ref,
+  provide,
+  useOnConnected,
+  useOnDisconnected,
+  registerBuiltinComponents,
+} from '@jasonshimmy/custom-elements-runtime'
+import { initRouter } from '@jasonshimmy/custom-elements-runtime/router'
+import { enableJITCSS } from '@jasonshimmy/custom-elements-runtime/jit-css'
+
+registerBuiltinComponents()
+enableJITCSS()
+
+const router = initRouter({ routes })
+
+const isNavigating = ref(false)
+const currentError = ref(null)
+;(globalThis as any).resetError = () => {
+  currentError.value = null
+  router.replace(router.getCurrent().path)
+}
+
+const _push = router.push.bind(router)
+const _replace = router.replace.bind(router)
+router.push = async (path) => {
+  isNavigating.value = true
+  currentError.value = null
+  try { await _push(path) } catch (err) { currentError.value = err instanceof Error ? err.message : String(err) } finally { isNavigating.value = false }
+}
+router.replace = async (path) => {
+  isNavigating.value = true
+  currentError.value = null
+  try { await _replace(path) } catch (err) { currentError.value = err instanceof Error ? err.message : String(err) } finally { isNavigating.value = false }
+}
+
+const _pluginProvides = new Map<string, unknown>()
+;(globalThis as any).__cerPluginProvides = _pluginProvides
+
+component('cer-layout-view', () => {
+  for (const [key, value] of _pluginProvides) {
+    provide(key, value)
+  }
+
+  const current = ref(router.getCurrent())
+  let unsub: (() => void) | undefined
+  useOnConnected(() => { unsub = router.subscribe((s: typeof current.value) => { current.value = s }) })
+  useOnDisconnected(() => { unsub?.(); unsub = undefined })
+
+  if (currentError.value !== null) {
+    if (hasError && errorTag) return { tag: errorTag, props: { attrs: { error: String(currentError.value) } }, children: [] }
+    return { tag: 'div', props: { attrs: { style: 'padding:2rem;font-family:monospace' } }, children: String(currentError.value) }
+  }
+  if (isNavigating.value && hasLoading && loadingTag) return { tag: loadingTag, props: {}, children: [] }
+
+  const matched = router.matchRoute(current.value.path)
+  const layoutName = (matched?.route as any)?.meta?.layout ?? 'default'
+  const layoutTag = (layouts as Record<string, string>)[layoutName]
+  const routerView = { tag: 'router-view', props: {}, children: [] }
+  return layoutTag ? { tag: layoutTag, props: {}, children: [routerView] } : routerView
+})
+
+for (const plugin of plugins) {
+  if (plugin && typeof plugin.setup === 'function') {
+    await plugin.setup({ router, provide: (key: string, value: unknown) => { _pluginProvides.set(key, value) }, config: {} })
+  }
+}
+
+// Pre-load the current page's route chunk AFTER plugins run so that
+// cer-layout-view's first render (which calls provide()) completes before
+// page components are defined. This ensures inject() in child components
+// can find values stored by provide().
+if (typeof window !== 'undefined') {
+  const _initMatch = router.matchRoute(window.location.pathname)
+  if (_initMatch?.route?.load) {
+    try { await _initMatch.route.load() } catch { /* non-fatal */ }
+  }
+}
+
+if (typeof window !== 'undefined') {
+  // Use the original (unwrapped) replace so isNavigating stays false on first paint.
+  await _replace(window.location.pathname + window.location.search + window.location.hash)
+}
+
+export { router }

package/dist/cli/create/templates/spa/app/layouts/default.ts.tpl

@@ -0,0 +1,15 @@
+component('layout-default', () => {
+  return html`
+    <header>
+      <nav>
+        <router-link to="/">Home</router-link>
+      </nav>
+    </header>
+    <main>
+      <slot></slot>
+    </main>
+    <footer>
+      <p>Built with CER App</p>
+    </footer>
+  `
+})

package/dist/cli/create/templates/spa/app/pages/index.ts.tpl

@@ -0,0 +1,8 @@
+component('page-index', () => {
+  return html`
+    <div>
+      <h1>Welcome to {{projectName}}</h1>
+      <p>Edit <code>app/pages/index.ts</code> to get started.</p>
+    </div>
+  `
+})

package/dist/cli/create/templates/spa/cer.config.ts.tpl

@@ -0,0 +1,6 @@
+import { defineConfig } from '@jasonshimmy/vite-plugin-cer-app'
+
+export default defineConfig({
+  mode: 'spa',
+  autoImports: { components: true, composables: true, directives: true, runtime: true },
+})

package/dist/cli/create/templates/spa/index.html.tpl

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>{{projectName}}</title>
+  </head>
+  <body>
+    <cer-layout-view></cer-layout-view>
+    <script type="module" src="/app/app.ts"></script>
+  </body>
+</html>

package/dist/cli/create/templates/spa/package.json.tpl

@@ -0,0 +1,18 @@
+{
+  "name": "{{projectName}}",
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "cer-app dev",
+    "build": "cer-app build",
+    "preview": "cer-app preview"
+  },
+  "dependencies": {
+    "@jasonshimmy/custom-elements-runtime": "^3.1.1"
+  },
+  "devDependencies": {
+    "vite": "^5.0.0",
+    "@jasonshimmy/vite-plugin-cer-app": "^0.1.0",
+    "typescript": "^5.4.0"
+  }
+}

package/dist/cli/create/templates/ssg/app/app.ts.tpl

@@ -0,0 +1,97 @@
+import '@jasonshimmy/custom-elements-runtime/css'
+import 'virtual:cer-jit-css'
+import 'virtual:cer-components'
+import routes from 'virtual:cer-routes'
+import layouts from 'virtual:cer-layouts'
+import plugins from 'virtual:cer-plugins'
+import { hasLoading, loadingTag } from 'virtual:cer-loading'
+import { hasError, errorTag } from 'virtual:cer-error'
+import {
+  component,
+  ref,
+  provide,
+  useOnConnected,
+  useOnDisconnected,
+  registerBuiltinComponents,
+} from '@jasonshimmy/custom-elements-runtime'
+import { initRouter } from '@jasonshimmy/custom-elements-runtime/router'
+import { enableJITCSS } from '@jasonshimmy/custom-elements-runtime/jit-css'
+
+registerBuiltinComponents()
+enableJITCSS()
+
+const router = initRouter({ routes })
+
+const isNavigating = ref(false)
+const currentError = ref(null)
+;(globalThis as any).resetError = () => {
+  currentError.value = null
+  router.replace(router.getCurrent().path)
+}
+
+const _push = router.push.bind(router)
+const _replace = router.replace.bind(router)
+router.push = async (path) => {
+  isNavigating.value = true
+  currentError.value = null
+  try { await _push(path) } catch (err) { currentError.value = err instanceof Error ? err.message : String(err) } finally { isNavigating.value = false }
+}
+router.replace = async (path) => {
+  isNavigating.value = true
+  currentError.value = null
+  try { await _replace(path) } catch (err) { currentError.value = err instanceof Error ? err.message : String(err) } finally { isNavigating.value = false }
+}
+
+const _pluginProvides = new Map<string, unknown>()
+;(globalThis as any).__cerPluginProvides = _pluginProvides
+
+component('cer-layout-view', () => {
+  for (const [key, value] of _pluginProvides) {
+    provide(key, value)
+  }
+
+  const current = ref(router.getCurrent())
+  let unsub: (() => void) | undefined
+  useOnConnected(() => { unsub = router.subscribe((s: typeof current.value) => { current.value = s }) })
+  useOnDisconnected(() => { unsub?.(); unsub = undefined })
+
+  if (currentError.value !== null) {
+    if (hasError && errorTag) return { tag: errorTag, props: { attrs: { error: String(currentError.value) } }, children: [] }
+    return { tag: 'div', props: { attrs: { style: 'padding:2rem;font-family:monospace' } }, children: String(currentError.value) }
+  }
+  if (isNavigating.value && hasLoading && loadingTag) return { tag: loadingTag, props: {}, children: [] }
+
+  const matched = router.matchRoute(current.value.path)
+  const layoutName = (matched?.route as any)?.meta?.layout ?? 'default'
+  const layoutTag = (layouts as Record<string, string>)[layoutName]
+  const routerView = { tag: 'router-view', props: {}, children: [] }
+  return layoutTag ? { tag: layoutTag, props: {}, children: [routerView] } : routerView
+})
+
+for (const plugin of plugins) {
+  if (plugin && typeof plugin.setup === 'function') {
+    await plugin.setup({ router, provide: (key: string, value: unknown) => { _pluginProvides.set(key, value) }, config: {} })
+  }
+}
+
+// Pre-load the current page's route chunk AFTER plugins run so that
+// cer-layout-view's first render (which calls provide()) completes before
+// page components are defined. This ensures inject() in child components
+// can find values stored by provide().
+if (typeof window !== 'undefined') {
+  const _initMatch = router.matchRoute(window.location.pathname)
+  if (_initMatch?.route?.load) {
+    try { await _initMatch.route.load() } catch { /* non-fatal */ }
+  }
+}
+
+if (typeof window !== 'undefined') {
+  // Use the original (unwrapped) replace so isNavigating stays false on first
+  // paint — the loading component must not flash over pre-rendered SSG content.
+  await _replace(window.location.pathname + window.location.search + window.location.hash)
+  // Clear SSR hydration data after initial navigation so subsequent navigations
+  // don't accidentally reuse it.
+  delete (globalThis as any).__CER_DATA__
+}
+
+export { router }

package/dist/cli/create/templates/ssg/app/layouts/default.ts.tpl

@@ -0,0 +1,15 @@
+component('layout-default', () => {
+  return html`
+    <header>
+      <nav>
+        <router-link to="/">Home</router-link>
+      </nav>
+    </header>
+    <main>
+      <slot></slot>
+    </main>
+    <footer>
+      <p>Built with CER App</p>
+    </footer>
+  `
+})

package/dist/cli/create/templates/ssg/app/pages/index.ts.tpl

@@ -0,0 +1,8 @@
+component('page-index', () => {
+  return html`
+    <div>
+      <h1>Welcome to {{projectName}}</h1>
+      <p>Edit <code>app/pages/index.ts</code> to get started.</p>
+    </div>
+  `
+})

package/dist/cli/create/templates/ssg/cer.config.ts.tpl

@@ -0,0 +1,13 @@
+import { defineConfig } from '@jasonshimmy/vite-plugin-cer-app'
+
+export default defineConfig({
+  mode: 'ssg',
+  ssg: {
+    routes: 'auto',
+    concurrency: 4,
+  },
+  ssr: {
+    dsd: true,
+  },
+  autoImports: { components: true, composables: true, directives: true, runtime: true },
+})

package/dist/cli/create/templates/ssg/index.html.tpl

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>{{projectName}}</title>
+  </head>
+  <body>
+    <cer-layout-view></cer-layout-view>
+    <script type="module" src="/app/app.ts"></script>
+  </body>
+</html>

package/dist/cli/create/templates/ssg/package.json.tpl

@@ -0,0 +1,19 @@
+{
+  "name": "{{projectName}}",
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "cer-app dev",
+    "build": "cer-app build",
+    "generate": "cer-app generate",
+    "preview": "cer-app preview"
+  },
+  "dependencies": {
+    "@jasonshimmy/custom-elements-runtime": "^3.1.1"
+  },
+  "devDependencies": {
+    "vite": "^5.0.0",
+    "@jasonshimmy/vite-plugin-cer-app": "^0.1.0",
+    "typescript": "^5.4.0"
+  }
+}

package/dist/cli/create/templates/ssr/app/app.ts.tpl

@@ -0,0 +1,97 @@
+import '@jasonshimmy/custom-elements-runtime/css'
+import 'virtual:cer-jit-css'
+import 'virtual:cer-components'
+import routes from 'virtual:cer-routes'
+import layouts from 'virtual:cer-layouts'
+import plugins from 'virtual:cer-plugins'
+import { hasLoading, loadingTag } from 'virtual:cer-loading'
+import { hasError, errorTag } from 'virtual:cer-error'
+import {
+  component,
+  ref,
+  provide,
+  useOnConnected,
+  useOnDisconnected,
+  registerBuiltinComponents,
+} from '@jasonshimmy/custom-elements-runtime'
+import { initRouter } from '@jasonshimmy/custom-elements-runtime/router'
+import { enableJITCSS } from '@jasonshimmy/custom-elements-runtime/jit-css'
+
+registerBuiltinComponents()
+enableJITCSS()
+
+const router = initRouter({ routes })
+
+const isNavigating = ref(false)
+const currentError = ref(null)
+;(globalThis as any).resetError = () => {
+  currentError.value = null
+  router.replace(router.getCurrent().path)
+}
+
+const _push = router.push.bind(router)
+const _replace = router.replace.bind(router)
+router.push = async (path) => {
+  isNavigating.value = true
+  currentError.value = null
+  try { await _push(path) } catch (err) { currentError.value = err instanceof Error ? err.message : String(err) } finally { isNavigating.value = false }
+}
+router.replace = async (path) => {
+  isNavigating.value = true
+  currentError.value = null
+  try { await _replace(path) } catch (err) { currentError.value = err instanceof Error ? err.message : String(err) } finally { isNavigating.value = false }
+}
+
+const _pluginProvides = new Map<string, unknown>()
+;(globalThis as any).__cerPluginProvides = _pluginProvides
+
+component('cer-layout-view', () => {
+  for (const [key, value] of _pluginProvides) {
+    provide(key, value)
+  }
+
+  const current = ref(router.getCurrent())
+  let unsub: (() => void) | undefined
+  useOnConnected(() => { unsub = router.subscribe((s: typeof current.value) => { current.value = s }) })
+  useOnDisconnected(() => { unsub?.(); unsub = undefined })
+
+  if (currentError.value !== null) {
+    if (hasError && errorTag) return { tag: errorTag, props: { attrs: { error: String(currentError.value) } }, children: [] }
+    return { tag: 'div', props: { attrs: { style: 'padding:2rem;font-family:monospace' } }, children: String(currentError.value) }
+  }
+  if (isNavigating.value && hasLoading && loadingTag) return { tag: loadingTag, props: {}, children: [] }
+
+  const matched = router.matchRoute(current.value.path)
+  const layoutName = (matched?.route as any)?.meta?.layout ?? 'default'
+  const layoutTag = (layouts as Record<string, string>)[layoutName]
+  const routerView = { tag: 'router-view', props: {}, children: [] }
+  return layoutTag ? { tag: layoutTag, props: {}, children: [routerView] } : routerView
+})
+
+for (const plugin of plugins) {
+  if (plugin && typeof plugin.setup === 'function') {
+    await plugin.setup({ router, provide: (key: string, value: unknown) => { _pluginProvides.set(key, value) }, config: {} })
+  }
+}
+
+// Pre-load the current page's route chunk AFTER plugins run so that
+// cer-layout-view's first render (which calls provide()) completes before
+// page components are defined. This ensures inject() in child components
+// can find values stored by provide().
+if (typeof window !== 'undefined') {
+  const _initMatch = router.matchRoute(window.location.pathname)
+  if (_initMatch?.route?.load) {
+    try { await _initMatch.route.load() } catch { /* non-fatal */ }
+  }
+}
+
+if (typeof window !== 'undefined') {
+  // Use the original (unwrapped) replace so isNavigating stays false on first
+  // paint — the loading component must not flash over pre-rendered SSR content.
+  await _replace(window.location.pathname + window.location.search + window.location.hash)
+  // Clear SSR hydration data after initial navigation so subsequent navigations
+  // don't accidentally reuse it.
+  delete (globalThis as any).__CER_DATA__
+}
+
+export { router }

package/dist/cli/create/templates/ssr/app/layouts/default.ts.tpl

@@ -0,0 +1,15 @@
+component('layout-default', () => {
+  return html`
+    <header>
+      <nav>
+        <router-link to="/">Home</router-link>
+      </nav>
+    </header>
+    <main>
+      <slot></slot>
+    </main>
+    <footer>
+      <p>Built with CER App</p>
+    </footer>
+  `
+})

package/dist/cli/create/templates/ssr/app/pages/index.ts.tpl

@@ -0,0 +1,8 @@
+component('page-index', () => {
+  return html`
+    <div>
+      <h1>Welcome to {{projectName}}</h1>
+      <p>Edit <code>app/pages/index.ts</code> to get started.</p>
+    </div>
+  `
+})

package/dist/cli/create/templates/ssr/cer.config.ts.tpl

@@ -0,0 +1,10 @@
+import { defineConfig } from '@jasonshimmy/vite-plugin-cer-app'
+
+export default defineConfig({
+  mode: 'ssr',
+  ssr: {
+    dsd: true,
+    streaming: true,
+  },
+  autoImports: { components: true, composables: true, directives: true, runtime: true },
+})

package/dist/cli/create/templates/ssr/index.html.tpl

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>{{projectName}}</title>
+  </head>
+  <body>
+    <cer-layout-view></cer-layout-view>
+    <script type="module" src="/app/app.ts"></script>
+  </body>
+</html>

package/dist/cli/create/templates/ssr/package.json.tpl

@@ -0,0 +1,18 @@
+{
+  "name": "{{projectName}}",
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "cer-app dev",
+    "build": "cer-app build",
+    "preview": "cer-app preview --ssr"
+  },
+  "dependencies": {
+    "@jasonshimmy/custom-elements-runtime": "^3.1.1"
+  },
+  "devDependencies": {
+    "vite": "^5.0.0",
+    "@jasonshimmy/vite-plugin-cer-app": "^0.1.0",
+    "typescript": "^5.4.0"
+  }
+}

package/docs/cli.md

@@ -148,9 +148,11 @@ dist/
 
 Scaffolds a new project from a template.
 
-```sh
-create-cer-app [project-name] [options]
-```
+> **Note:** Because the scaffolder is bundled inside `@jasonshimmy/vite-plugin-cer-app` rather than published as a standalone `create-cer-app` package, you must use the `--package` flag with `npx`:
+>
+> ```sh
+> npx --package @jasonshimmy/vite-plugin-cer-app create-cer-app [project-name] [options]
+> ```
 
 | Argument / Option | Description |
 |---|---|
@@ -161,10 +163,10 @@ create-cer-app [project-name] [options]
 **Examples:**
 
 ```sh
-create-cer-app                          # interactive prompts
-create-cer-app my-app                   # prompts for mode
-create-cer-app my-app --mode ssr        # no prompts
-create-cer-app my-blog --mode ssg --dir ./sites/blog
+npx --package @jasonshimmy/vite-plugin-cer-app create-cer-app                          # interactive prompts
+npx --package @jasonshimmy/vite-plugin-cer-app create-cer-app my-app                   # prompts for mode
+npx --package @jasonshimmy/vite-plugin-cer-app create-cer-app my-app --mode ssr        # no prompts
+npx --package @jasonshimmy/vite-plugin-cer-app create-cer-app my-blog --mode ssg --dir ./sites/blog
 ```
 
 **Scaffolded files (all modes):**
@@ -231,5 +233,5 @@ npm run preview
 ```sh
 npx cer-app dev
 npx cer-app build
-npx create-cer-app my-app
+npx --package @jasonshimmy/vite-plugin-cer-app create-cer-app my-app
 ```

package/docs/configuration.md

@@ -217,8 +217,10 @@ When `runtime: true`, the following are injected if used and not already importe
 ```ts
 import { component, html, css, ref, computed, watch, watchEffect,
          useProps, useEmit, useOnConnected, useOnDisconnected,
-         useOnAttributeChanged, useOnError, useStyle, useExpose,
-         useSlots, provide, inject, createComposable, nextTick
+         useOnAttributeChanged, useOnError, useStyle, useDesignTokens,
+         useGlobalStyle, useExpose, useSlots, provide, inject,
+         createComposable, nextTick, defineModel, getCurrentComponentContext,
+         isReactiveState, unsafeHTML, decodeEntities, useTeleport
 } from '@jasonshimmy/custom-elements-runtime'
 ```
 

package/docs/getting-started.md

@@ -11,7 +11,7 @@
 ## Option A — Scaffold with `create-cer-app` (recommended)
 
 ```sh
-npx create-cer-app my-app
+npx --package @jasonshimmy/vite-plugin-cer-app create-cer-app my-app
 ```
 
 The interactive prompt asks for a project name and rendering mode:
@@ -39,7 +39,7 @@ Project created! To get started:
 You can also skip the prompts with flags:
 
 ```sh
-npx create-cer-app my-app --mode ssr
+npx --package @jasonshimmy/vite-plugin-cer-app create-cer-app my-app --mode ssr
 ```
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jasonshimmy/vite-plugin-cer-app",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Nuxt-style meta-framework for @jasonshimmy/custom-elements-runtime",
   "type": "module",
   "keywords": [
@@ -44,7 +44,7 @@
     "create-cer-app": "./dist/cli/create/index.js"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
+    "build": "tsc -p tsconfig.build.json && cp -r src/cli/create/templates dist/cli/create/templates",
     "dev": "tsc -p tsconfig.build.json --watch",
     "test": "vitest run",
     "test:watch": "vitest",