@govela/create 0.0.0-stage → 0.7.0

package/templates/default/base/AGENTS.md

@@ -0,0 +1,28 @@
+# Agent instructions
+
+This is a Vela application. Before you create or edit a `.vela` component,
+read the Vela authoring guide of the compiler version this project uses:
+
+https://github.com/elauven/vela/blob/v__VERSION__/AGENTS.md
+
+It defines the component shape, the runes (`$state`, `$derived`,
+`$effect`, `$bindable`), the template syntax (`:attr={…}`, `@event={…}`,
+`{#if}`, `{#each}`) and what Vela does not support. When a compiler
+diagnostic disagrees with an example, trust the diagnostic.
+
+## This project
+
+- Components live in `src/`; `src/main.__EXT__` mounts `src/App.vela`.
+- Tests are `*.test.__EXT__` files next to the components, run by Vitest with
+  `@govela/testing` (`render`, `fireEvent`).
+
+## Before handing off
+
+```sh
+npm run check   # vela check: compiler diagnostics (and types, in TypeScript)
+npm run lint    # eslint: the code of the components and modules
+npm test        # vitest run
+npm run build   # vite build
+```
+
+All of them must pass.

package/templates/default/base/README.md

@@ -0,0 +1,17 @@
+# __NAME__
+
+A [Vela](https://github.com/elauven/vela) application: Vite with
+`@govela/unplugin`, Vitest with `@govela/testing`, ESLint with
+`@govela/eslint-plugin`.
+
+```sh
+npm install
+npm run dev     # http://localhost:5173
+npm test        # component tests
+npm run check   # compiler diagnostics
+npm run lint    # eslint
+npm run build   # production build into dist/
+```
+
+`.github/workflows/ci.yml` runs the check, the linter, the tests and the build on every
+push.

package/templates/default/base/_github/workflows/ci.yml

@@ -0,0 +1,20 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v5
+        with:
+          node-version: '24'
+          cache: npm
+      - run: npm ci
+      - run: npm run check
+      - run: npm run lint
+      - run: npm test
+      - run: npm run build

package/templates/default/base/_gitignore

@@ -0,0 +1,2 @@
+/node_modules/
+/dist/

package/templates/default/base/index.html

@@ -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>__NAME__</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.__EXT__"></script>
+  </body>
+</html>

package/templates/default/base/vite.config.js

@@ -0,0 +1,9 @@
+import vela from '@govela/unplugin/vite';
+
+export default {
+  plugins: [vela()],
+  test: {
+    environment: 'happy-dom',
+    setupFiles: ['./vitest.setup.__EXT__'],
+  },
+};

package/templates/default/base/vitest.setup.__EXT__

@@ -0,0 +1,5 @@
+import { afterEach } from 'vitest';
+import { cleanup } from '@govela/testing';
+
+// Every test starts with an empty document.
+afterEach(cleanup);

package/templates/default/js/eslint.config.js

@@ -0,0 +1,12 @@
+import { defineConfig } from 'eslint/config';
+import js from '@eslint/js';
+import globals from 'globals';
+import vela from '@govela/eslint-plugin';
+
+export default defineConfig(
+  { ignores: ['dist/', 'out/', 'build/', 'src/_app/'] },
+  js.configs.recommended,
+  vela.configs.recommended,
+  { files: ['src/**/*.js', '**/*.vela/*.js'], languageOptions: { globals: globals.browser } },
+  { files: ['*.config.js'], languageOptions: { globals: globals.node } },
+);

package/templates/default/js/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "__NAME__",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "check": "vela check --project src",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "build": "vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@govela/runtime": "__VERSION__"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@govela/compiler": "__VERSION__",
+    "@govela/eslint-plugin": "__VERSION__",
+    "@govela/testing": "__VERSION__",
+    "@govela/unplugin": "__VERSION__",
+    "eslint": "^10.14.0",
+    "globals": "^17.0.0",
+    "happy-dom": "^21.0.4",
+    "vite": "^8.3.5",
+    "vitest": "^5.1.0"
+  }
+}

package/templates/default/js/src/App.vela

@@ -0,0 +1,25 @@
+<script>
+  import Counter from './Counter.vela';
+
+  let total = $state(0);
+
+  function changed(event) {
+    total = event.detail;
+  }
+</script>
+
+<template>
+  <main>
+    <h1>Vela</h1>
+    <Counter :step={1} @on:change={changed}>Clicks</Counter>
+    <p class="total">Total: {total}</p>
+  </main>
+</template>
+
+<style>
+  main {
+    font-family: system-ui, sans-serif;
+    max-width: 32rem;
+    margin: 4rem auto;
+  }
+</style>

package/templates/default/js/src/Counter.test.js

@@ -0,0 +1,20 @@
+import { expect, test } from 'vitest';
+import { fireEvent, render } from '@govela/testing';
+import Counter from './Counter.vela';
+
+test('counts by its step and reports the count', async () => {
+  const counts = [];
+  const { container } = render(Counter, {
+    props: { step: 2 },
+    slots: { default: 'Clicks' },
+    events: { change: (event) => counts.push(event.detail) },
+  });
+  const button = container.querySelector('button');
+  expect(button.textContent).toBe('Clicks: 0');
+
+  await fireEvent.click(button);
+  await fireEvent.click(button);
+
+  expect(button.textContent).toBe('Clicks: 4');
+  expect(counts).toEqual([2, 4]);
+});

package/templates/default/js/src/Counter.vela

@@ -0,0 +1,23 @@
+<script>
+  export let step = 1;
+
+  let count = $state(0);
+
+  function increment() {
+    count += step;
+    $$dispatch('change', count);
+  }
+</script>
+
+<template>
+  <button @click={increment}>
+    <slot>Count</slot>: {count}
+  </button>
+</template>
+
+<style>
+  button {
+    font: inherit;
+    padding: 0.5rem 1rem;
+  }
+</style>

package/templates/default/js/src/main.js

@@ -0,0 +1,4 @@
+import { mount } from '@govela/runtime';
+import App from './App.vela';
+
+mount(App, { target: document.getElementById('app') });

package/templates/default/ts/eslint.config.js

@@ -0,0 +1,14 @@
+import { defineConfig } from 'eslint/config';
+import js from '@eslint/js';
+import globals from 'globals';
+import tseslint from 'typescript-eslint';
+import vela from '@govela/eslint-plugin';
+
+export default defineConfig(
+  { ignores: ['dist/', 'out/', 'build/', 'src/_app/'] },
+  js.configs.recommended,
+  tseslint.configs.recommended,
+  vela.configs.recommended,
+  { files: ['src/**/*.ts', '**/*.vela/*.ts'], languageOptions: { globals: globals.browser } },
+  { files: ['*.config.js'], languageOptions: { globals: globals.node } },
+);

package/templates/default/ts/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "__NAME__",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "check": "vela check --project src --types",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "build": "vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "@govela/runtime": "__VERSION__"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@govela/compiler": "__VERSION__",
+    "@govela/eslint-plugin": "__VERSION__",
+    "@govela/testing": "__VERSION__",
+    "@govela/unplugin": "__VERSION__",
+    "eslint": "^10.14.0",
+    "globals": "^17.0.0",
+    "happy-dom": "^21.0.4",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.72.1",
+    "vite": "^8.3.5",
+    "vitest": "^5.1.0"
+  }
+}

package/templates/default/ts/src/App.vela

@@ -0,0 +1,25 @@
+<script lang="ts">
+  import Counter from './Counter.vela';
+
+  let total = $state(0);
+
+  function changed(event: CustomEvent<number>): void {
+    total = event.detail;
+  }
+</script>
+
+<template>
+  <main>
+    <h1>Vela</h1>
+    <Counter :step={1} @on:change={changed}>Clicks</Counter>
+    <p class="total">Total: {total}</p>
+  </main>
+</template>
+
+<style>
+  main {
+    font-family: system-ui, sans-serif;
+    max-width: 32rem;
+    margin: 4rem auto;
+  }
+</style>

package/templates/default/ts/src/Counter.test.ts

@@ -0,0 +1,20 @@
+import { expect, test } from 'vitest';
+import { fireEvent, render } from '@govela/testing';
+import Counter from './Counter.vela';
+
+test('counts by its step and reports the count', async () => {
+  const counts: number[] = [];
+  const { container } = render(Counter, {
+    props: { step: 2 },
+    slots: { default: 'Clicks' },
+    events: { change: (event) => counts.push(event.detail) },
+  });
+  const button = container.querySelector('button')!;
+  expect(button.textContent).toBe('Clicks: 0');
+
+  await fireEvent.click(button);
+  await fireEvent.click(button);
+
+  expect(button.textContent).toBe('Clicks: 4');
+  expect(counts).toEqual([2, 4]);
+});

package/templates/default/ts/src/Counter.vela

@@ -0,0 +1,27 @@
+<script lang="ts">
+  interface $$Events {
+    change: number;
+  }
+
+  export let step: number = 1;
+
+  let count = $state(0);
+
+  function increment(): void {
+    count += step;
+    $$dispatch('change', count);
+  }
+</script>
+
+<template>
+  <button @click={increment}>
+    <slot>Count</slot>: {count}
+  </button>
+</template>
+
+<style>
+  button {
+    font: inherit;
+    padding: 0.5rem 1rem;
+  }
+</style>

package/templates/default/ts/src/main.ts

@@ -0,0 +1,4 @@
+import { mount } from '@govela/runtime';
+import App from './App.vela';
+
+mount(App, { target: document.getElementById('app')! });

package/templates/default/ts/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noEmit": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true,
+    "erasableSyntaxOnly": true,
+    "allowImportingTsExtensions": true,
+    "useDefineForClassFields": true,
+    "skipLibCheck": true,
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "types": ["@govela/runtime/ambient"]
+  },
+  "include": ["src"]
+}

package/templates/ssr/base/AGENTS.md

@@ -0,0 +1,34 @@
+# Agent instructions
+
+This is a server-rendered Vela application. Before you create or edit a
+`.vela` component, read the Vela authoring guide of the compiler version
+this project uses:
+
+https://github.com/elauven/vela/blob/v__VERSION__/AGENTS.md
+
+It defines the component shape, the runes, the template syntax, the rules
+of server rendering and what Vela does not support. When a compiler
+diagnostic disagrees with an example, trust the diagnostic.
+
+## This project
+
+- Components live in `src/`. `vela` (configured by `vela.config.json`)
+  compiles them to Go renderers in `out/server`; `cmd/server` renders
+  `App` with them; `src/client.__EXT__` hydrates the HTML in the browser.
+- Code that runs during the first render is translated to Go: keep it free
+  of browser APIs (`window`, `document`, `Date.now()`). Put browser work in
+  handlers, `$effect` or `onMount`. Treat every `VELA-SSR-*` diagnostic as
+  an error to fix.
+- Tests are `*.test.__EXT__` files next to the components, run by Vitest with
+  `@govela/testing` (`render`, `fireEvent`).
+
+## Before handing off
+
+```sh
+npm run check   # vela check --ssr: compiler and server-rendering diagnostics (and types)
+npm run lint    # eslint: the code of the components and modules
+npm test        # vitest run
+npm run build   # vela, vite build and go build
+```
+
+All of them must pass.

package/templates/ssr/base/README.md

@@ -0,0 +1,30 @@
+# __NAME__
+
+A server-rendered [Vela](https://github.com/elauven/vela) application: the
+Go server in `cmd/server` renders the components, Vite with
+`@govela/unplugin` builds the client that hydrates them, Vitest with
+`@govela/testing` tests them.
+
+```sh
+npm install
+go mod tidy
+```
+
+Development, three processes:
+
+```sh
+npm run dev:vela     # vela --watch: Go renderers into out/
+npm run dev          # Vite on http://localhost:5173
+npm run dev:server   # the Go server on http://127.0.0.1:8080
+```
+
+Restart the Go server after a change of a component (`out/.vela-ready`
+is written after every successful build).
+
+```sh
+npm test             # component tests
+npm run check        # compiler and server-rendering diagnostics
+npm run lint         # eslint
+npm run build        # out/, dist/ and build/server
+npm start            # the production server, serving dist/
+```

package/templates/ssr/base/_github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-go@v6
+        with:
+          go-version-file: go.mod
+      - uses: actions/setup-node@v5
+        with:
+          node-version: '24'
+          cache: npm
+      - run: npm ci
+      - run: npm run check
+      - run: npm run lint
+      - run: npm test
+      - run: npm run build

package/templates/ssr/base/_gitignore

@@ -0,0 +1,4 @@
+/node_modules/
+/dist/
+/out/
+/build/

package/templates/ssr/base/cmd/server/main.go

@@ -0,0 +1,57 @@
+// The server: renders App with the Go renderer `vela` generates into
+// out/server, and adds the client from the Vite dev server (-dev) or from
+// the output of vite build (-dist).
+package main
+
+import (
+	"flag"
+	"fmt"
+	"log"
+	"net"
+	"net/http"
+	"path/filepath"
+
+	"github.com/elauven/vela/ssr_runtime/vite"
+
+	components "__MODULE__/out/server/components"
+)
+
+func main() {
+	addr := flag.String("addr", "127.0.0.1:8080", "listen address")
+	dev := flag.String("dev", "", "URL of the Vite dev server; serve dist/ when empty")
+	dist := flag.String("dist", "dist", "output directory of vite build")
+	flag.Parse()
+
+	mux := http.NewServeMux()
+	var assets *vite.Assets
+	if *dev != "" {
+		assets = vite.Dev(*dev)
+	} else {
+		var err error
+		if assets, err = vite.Load(filepath.Join(*dist, ".vite", "manifest.json"), "/"); err != nil {
+			log.Fatal(err)
+		}
+		mux.Handle("/assets/", http.FileServer(http.Dir(*dist)))
+	}
+	tags, err := assets.Tags("src/client.__EXT__")
+	if err != nil {
+		log.Fatal(err)
+	}
+
+	mux.HandleFunc("/{$}", func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "text/html; charset=utf-8")
+		fmt.Fprintf(w, "<!doctype html><html><head><meta charset=\"utf-8\">%s</head><body><div id=\"app\">", tags)
+		props := components.AppProps{Set: map[string]bool{"title": true}, Title: "Vela"}
+		if err := components.RenderAppContext(r.Context(), w, props, components.AppSlots{}); err != nil {
+			log.Print(err)
+		}
+		fmt.Fprint(w, "</div></body></html>")
+	})
+
+	listener, err := net.Listen("tcp", *addr)
+	if err != nil {
+		log.Fatal(err)
+	}
+	fmt.Println("http://" + listener.Addr().String() + "/")
+	log.Fatal(http.Serve(listener, mux))
+}

package/templates/ssr/base/go.mod

@@ -0,0 +1,5 @@
+module __MODULE__
+
+go 1.25
+
+require github.com/elauven/vela/ssr_runtime v__VERSION__

package/templates/ssr/base/vela.config.json

@@ -0,0 +1,6 @@
+{
+  "project": "src",
+  "out": "out",
+  "ssr": true,
+  "ssrModule": "__MODULE__/out/server"
+}

package/templates/ssr/base/vite.config.js

@@ -0,0 +1,11 @@
+import vela from '@govela/unplugin/vite';
+
+export default {
+  plugins: [vela()],
+  server: { origin: 'http://localhost:5173' },
+  build: { manifest: true, rollupOptions: { input: 'src/client.__EXT__' } },
+  test: {
+    environment: 'happy-dom',
+    setupFiles: ['./vitest.setup.__EXT__'],
+  },
+};

package/templates/ssr/base/vitest.setup.__EXT__

@@ -0,0 +1,5 @@
+import { afterEach } from 'vitest';
+import { cleanup } from '@govela/testing';
+
+// Every test starts with an empty document.
+afterEach(cleanup);

package/templates/ssr/js/eslint.config.js

@@ -0,0 +1,12 @@
+import { defineConfig } from 'eslint/config';
+import js from '@eslint/js';
+import globals from 'globals';
+import vela from '@govela/eslint-plugin';
+
+export default defineConfig(
+  { ignores: ['dist/', 'out/', 'build/', 'src/_app/'] },
+  js.configs.recommended,
+  vela.configs.recommended,
+  { files: ['src/**/*.js', '**/*.vela/*.js'], languageOptions: { globals: globals.browser } },
+  { files: ['*.config.js'], languageOptions: { globals: globals.node } },
+);

package/templates/ssr/js/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "__NAME__",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "dev:vela": "vela --watch",
+    "dev:server": "go run ./cmd/server -dev http://localhost:5173",
+    "check": "vela check --project src --ssr",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "build": "vela && vite build && go build -o build/server ./cmd/server",
+    "start": "./build/server"
+  },
+  "dependencies": {
+    "@govela/runtime": "__VERSION__"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@govela/compiler": "__VERSION__",
+    "@govela/eslint-plugin": "__VERSION__",
+    "@govela/testing": "__VERSION__",
+    "@govela/unplugin": "__VERSION__",
+    "eslint": "^10.14.0",
+    "globals": "^17.0.0",
+    "happy-dom": "^21.0.4",
+    "vite": "^8.3.5",
+    "vitest": "^5.1.0"
+  }
+}

package/templates/ssr/js/src/App.vela

@@ -0,0 +1,27 @@
+<script>
+  import Counter from './Counter.vela';
+
+  export let title = 'Vela';
+
+  let total = $state(0);
+
+  function changed(event) {
+    total = event.detail;
+  }
+</script>
+
+<template>
+  <main>
+    <h1>{title}</h1>
+    <Counter :step={1} @on:change={changed}>Clicks</Counter>
+    <p class="total">Total: {total}</p>
+  </main>
+</template>
+
+<style>
+  main {
+    font-family: system-ui, sans-serif;
+    max-width: 32rem;
+    margin: 4rem auto;
+  }
+</style>

package/templates/ssr/js/src/Counter.test.js

@@ -0,0 +1,20 @@
+import { expect, test } from 'vitest';
+import { fireEvent, render } from '@govela/testing';
+import Counter from './Counter.vela';
+
+test('counts by its step and reports the count', async () => {
+  const counts = [];
+  const { container } = render(Counter, {
+    props: { step: 2 },
+    slots: { default: 'Clicks' },
+    events: { change: (event) => counts.push(event.detail) },
+  });
+  const button = container.querySelector('button');
+  expect(button.textContent).toBe('Clicks: 0');
+
+  await fireEvent.click(button);
+  await fireEvent.click(button);
+
+  expect(button.textContent).toBe('Clicks: 4');
+  expect(counts).toEqual([2, 4]);
+});