create-backbone-template 0.1.0

package/template/Cargo.toml

@@ -0,0 +1,29 @@
+[workspace]
+members = ["server"]
+resolver = "3"
+
+[workspace.package]
+edition = "2024"
+rust-version = "1.88"
+license = "MIT"
+
+[workspace.metadata.dylint]
+libraries = [{ path = "server/dylint/backbone_server_lints" }]
+
+[workspace.lints.clippy]
+correctness = { level = "deny", priority = -1 }
+dbg_macro = "deny"
+exit = "deny"
+expect_used = "deny"
+mem_forget = "deny"
+missing_errors_doc = "allow"
+panic = "deny"
+pedantic = { level = "warn", priority = -1 }
+perf = { level = "deny", priority = -1 }
+print_stderr = "deny"
+print_stdout = "deny"
+suspicious = { level = "deny", priority = -1 }
+todo = "deny"
+undocumented_unsafe_blocks = "deny"
+unimplemented = "deny"
+unwrap_used = "deny"

package/template/Justfile

@@ -0,0 +1,140 @@
+set shell := ["bash", "-c"]
+set tempdir := "/tmp"
+varlock := "pnpm exec varlock run --no-inject-graph --"
+
+default:
+    @just --list
+
+setup:
+    pnpm install
+    pnpm --filter backbone-e2e exec playwright install chromium
+    cargo fetch
+
+generate:
+    pnpm --filter backbone-client exec buf generate --template ../buf.gen.yaml --output .. ../proto
+
+proto-lint:
+    pnpm --filter backbone-client exec buf lint ../proto
+
+server:
+    {{varlock}} cargo run -p server
+
+client:
+    {{varlock}} pnpm --filter backbone-client run dev
+
+ladle:
+    {{varlock}} pnpm --filter backbone-client run ladle
+
+pr-slide-generate:
+    pnpm --filter @backbone/pr-slide run generate
+
+pr-slide:
+    pnpm --filter @backbone/pr-slide run dev
+
+pr-slide-list:
+    pnpm --filter @backbone/pr-slide run list
+
+pr-slide-open name *args:
+    pnpm --filter @backbone/pr-slide run open -- {{name}} {{args}}
+
+client-test:
+    pnpm --filter backbone-client test
+
+rust-test:
+    cargo test --workspace
+
+rust-clippy:
+    cargo clippy --workspace --all-targets
+
+rust-lint:
+    cargo dylint --all -- --all-targets
+
+dev: generate
+    #!/usr/bin/env bash
+    set -euo pipefail
+
+    {{varlock}} cargo run -p server &
+    server_pid=$!
+
+    {{varlock}} pnpm --filter backbone-client run dev &
+    client_pid=$!
+
+    cleanup() {
+      kill "$server_pid" "$client_pid" 2>/dev/null || true
+      wait "$server_pid" "$client_pid" 2>/dev/null || true
+    }
+
+    trap cleanup EXIT INT TERM
+    wait -n "$server_pid" "$client_pid"
+
+check:
+    just proto-lint
+    just generate
+    just rust-validation-checks
+    just client-validation
+    pnpm --filter backbone-e2e run lint
+
+rust-validation-checks:
+    cargo check --workspace
+    just rust-clippy
+    just rust-lint
+
+client-validation:
+    just client-test
+    pnpm --filter backbone-client run check
+    pnpm --filter backbone-client run build
+
+full-validation:
+    #!/usr/bin/env bash
+    set -euo pipefail
+
+    just proto-lint
+    just generate
+
+    just rust-validation-checks &
+    rust_checks_pid=$!
+    just rust-test &
+    rust_test_pid=$!
+    pnpm --filter @backbone/design-system-lint build
+    pnpm --filter backbone-client run test:prepared &
+    client_test_pid=$!
+    pnpm --filter backbone-client run check:prepared &
+    client_check_pid=$!
+    pnpm --filter backbone-client run build &
+    client_build_pid=$!
+    pnpm --filter backbone-e2e run build:oxlint-plugin
+    pnpm --filter backbone-e2e run lint:prepared &
+    e2e_lint_pid=$!
+    pnpm --filter backbone-e2e run test:support:prepared &
+    e2e_support_pid=$!
+
+    status=0
+    for pid in "$rust_checks_pid" "$rust_test_pid" "$client_test_pid" "$client_check_pid" "$client_build_pid" "$e2e_lint_pid" "$e2e_support_pid"; do
+      if ! wait "$pid"; then
+        status=1
+      fi
+    done
+
+    if [[ "$status" -ne 0 ]]; then
+      exit "$status"
+    fi
+
+    BACKBONE_SKIP_GENERATE=1 just e2e-browser
+
+env-check:
+    pnpm exec varlock load
+
+e2e:
+    bash scripts/run-e2e.sh pnpm --filter backbone-e2e test
+
+e2e-prepared:
+    bash scripts/run-e2e.sh pnpm --filter backbone-e2e run test:prepared
+
+e2e-browser:
+    bash scripts/run-e2e.sh pnpm --filter backbone-e2e run test:browser
+
+e2e-debug:
+    bash scripts/run-e2e.sh pnpm --filter backbone-e2e run test:debug
+
+e2e-ui:
+    bash scripts/run-e2e.sh pnpm --filter backbone-e2e run test:ui

package/template/README.md

@@ -0,0 +1,72 @@
+# Backbone
+
+React + Rust ConnectRPC starter.
+
+## Layout
+
+- `client/` - React app built with Vite, pnpm workspaces, Oxlint, and Oxfmt
+- `server/` - Rust ConnectRPC server
+- `proto/` - shared protobuf definitions
+- `e2e/` - Playwright browser tests
+
+## Client Packages
+
+The client is a pnpm workspace rooted at `client/`.
+
+- `backbone-client` (`client/`) - Vite React application package. It owns the app entry point, generated ConnectRPC TypeScript bindings, client-side scripts, and dependencies on the design system and ConnectRPC web client.
+- `@backbone/design-system` (`client/packages/design-system/`) - public design-system boundary for app code. It re-exports the active component implementation from `@backbone/design-system-basic` and the shared component types from `@backbone/design-system-contract`.
+- `@backbone/design-system-contract` (`client/packages/design-system-contract/`) - type-only contract for supported UI primitives, including layout, stack, inline, text, headings, form fields, inputs, buttons, and notices.
+- `@backbone/design-system-basic` (`client/packages/design-system-basic/`) - concrete React and CSS implementation of the design-system contract. It contains the DOM markup and styling used by the app.
+- `@backbone/design-system-lint` (`client/packages/design-system-lint/`) - custom Oxlint plugin that protects the design-system boundary by rejecting raw DOM JSX in app code and direct imports from external UI libraries.
+
+## Rust Custom Lints
+
+The server has custom Dylint rules in `server/dylint/backbone_server_lints/`.
+They protect server architecture boundaries, such as keeping sqlx usage in
+`server/src/db/`, environment reads in config code, and RPC method
+implementations split into per-method files.
+
+The Dylint crate intentionally contains its own empty `[workspace]` table. That
+is the small Cargo hack that lets the lint crate live under `server/` while
+staying out of the root Cargo workspace's normal `cargo check` and `cargo test`
+paths. Dylint still builds it explicitly through the root
+`[workspace.metadata.dylint]` entry, but regular server compilation does not
+treat the lint implementation as application code.
+
+## Commands
+
+```sh
+just setup           # install JS deps, Playwright Chromium, and fetch cargo deps
+just generate        # generate React protobuf definitions from proto/
+just check           # generate, cargo check, client check, vite build
+just rust-test       # run Rust tests
+just full-validation # run check, Rust tests, and e2e tests
+just dev             # run the React client and Rust server together
+just ladle           # run the client design-system Ladle
+just e2e             # start client/server and test through the UI
+just e2e-debug       # run e2e headed/debug, stopping after the first failure
+just e2e-ui          # open Playwright UI mode
+```
+
+The dev launcher starts the client at `http://127.0.0.1:5173` and the server at
+`http://127.0.0.1:8080`, then stops both child processes when the launcher exits.
+
+## Runtime Configuration
+
+The starter keeps SQLite wired in so new features have a real persistence path
+from day one. The hello-world RPC records each submitted name in
+`hello_world_inputs`.
+
+Required server environment variables:
+
+```sh
+DATABASE_URL=sqlite://backbone.sqlite?mode=rwc
+SERVER_HOST=127.0.0.1
+SERVER_PORT=8080
+```
+
+Required client environment variables:
+
+```sh
+VITE_SERVER_URL=http://127.0.0.1:8080
+```

package/template/TODO.md

@@ -0,0 +1 @@
+- Add a linter for unused design system components ?

package/template/_gitignore

@@ -0,0 +1,12 @@
+target
+node_modules
+client/dist
+client/node_modules
+e2e/node_modules
+e2e/playwright-report
+e2e/test-results
+e2e/support/dist
+.agents/pr-presentation/**/dist
+pr-slide/dist
+*.local
+backbone.sqlite

package/template/buf.gen.yaml

@@ -0,0 +1,7 @@
+version: v2
+clean: true
+plugins:
+  - local: protoc-gen-es
+    out: client/src/gen
+    opt:
+      - target=ts

package/template/buf.yaml

@@ -0,0 +1,10 @@
+version: v2
+modules:
+  - path: proto
+lint:
+  use:
+    - STANDARD
+breaking:
+  use:
+    - FILE
+

package/template/client/.oxfmtrc.json

@@ -0,0 +1,8 @@
+{
+  "ignorePatterns": ["dist/**", "node_modules/**", "src/gen/**"],
+  "printWidth": 100,
+  "semi": false,
+  "singleQuote": false,
+  "tabWidth": 2,
+  "trailingComma": "all"
+}

package/template/client/.oxlintrc.json

@@ -0,0 +1,57 @@
+{
+  "$schema": "./node_modules/oxlint/configuration_schema.json",
+  "plugins": [
+    "eslint",
+    "typescript",
+    "unicorn",
+    "oxc",
+    "import",
+    "react",
+    "react-perf",
+    "jsx-a11y",
+    "promise",
+    "vitest"
+  ],
+  "jsPlugins": ["./packages/design-system-lint/dist/src/oxlint-plugin.js"],
+  "categories": {
+    "correctness": "deny",
+    "suspicious": "deny",
+    "perf": "deny",
+    "pedantic": "off",
+    "style": "off",
+    "restriction": "off",
+    "nursery": "off"
+  },
+  "options": {
+    "denyWarnings": true,
+    "reportUnusedDisableDirectives": "deny",
+    "typeAware": true
+  },
+  "ignorePatterns": ["src/gen/**", "packages/design-system-lint/fixtures/**"],
+  "rules": {
+    "import/no-unassigned-import": "off",
+    "react/react-in-jsx-scope": "off",
+    "react-perf/jsx-no-jsx-as-prop": "off",
+    "react-perf/jsx-no-new-array-as-prop": "off",
+    "react-perf/jsx-no-new-function-as-prop": "off",
+    "react-perf/jsx-no-new-object-as-prop": "off",
+    "typescript/no-unsafe-type-assertion": "off",
+    "typescript/unbound-method": "off",
+    "unicorn/no-array-sort": "off"
+  },
+  "overrides": [
+    {
+      "files": ["**/*.test.{ts,tsx}"],
+      "rules": {
+        "typescript/no-floating-promises": "off"
+      }
+    },
+    {
+      "files": ["src/**/*.{jsx,tsx}"],
+      "rules": {
+        "backbone-design-system/no-external-ui-imports": "error",
+        "backbone-design-system/no-raw-dom-jsx": "error"
+      }
+    }
+  ]
+}

package/template/client/README.md

@@ -0,0 +1,19 @@
+# Client
+
+React client application built with Vite and TypeScript, using pnpm workspaces,
+Oxlint, and Oxfmt.
+
+## Design system
+
+The client UI is composed through `@backbone/design-system`, which re-exports a concrete implementation while preserving the abstract component contract from `@backbone/design-system-contract`. App code imports layout, text, form, and control primitives from that boundary instead of rendering DOM elements directly. The actual HTML and styling live inside the design-system implementation package, so the app stays decoupled from markup and visual details. A custom Oxlint plugin enforces this by rejecting raw DOM JSX and direct imports from external UI libraries outside the design-system boundary.
+
+## Scripts
+
+```sh
+pnpm install
+pnpm run dev
+pnpm run typecheck
+pnpm run lint
+pnpm run format
+pnpm run check
+```

package/template/client/_gitignore

@@ -0,0 +1,5 @@
+dist
+build
+node_modules
+*.local
+packages/design-system-lint/dist

package/template/client/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.0" />
+    <title>Backbone Client</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

package/template/client/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "backbone-client",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "ladle": "ladle serve --stories \"{packages/design-system-basic/src,src}/**/*.stories.{ts,tsx}\" --viteConfig ./vite.ladle.config.ts",
+    "ladle:build": "ladle build --stories \"{packages/design-system-basic/src,src}/**/*.stories.{ts,tsx}\" --viteConfig ./vite.ladle.config.ts",
+    "build": "vite build",
+    "preview": "vite preview",
+    "typecheck": "tsc --noEmit",
+    "lint": "pnpm --filter @backbone/design-system-lint build && pnpm --filter @backbone/design-system-lint run check:architecture && oxlint .",
+    "lint:prepared": "pnpm --filter @backbone/design-system-lint run check:architecture && oxlint .",
+    "test": "pnpm --filter @backbone/design-system-lint test && vitest run src packages/design-system-basic/src",
+    "test:prepared": "pnpm --filter @backbone/design-system-lint run test:prepared && vitest run src packages/design-system-basic/src",
+    "format": "oxfmt .",
+    "format:check": "oxfmt --check .",
+    "check": "pnpm run format:check && pnpm run lint && pnpm run typecheck",
+    "check:prepared": "pnpm run format:check && pnpm run lint:prepared && pnpm run typecheck"
+  },
+  "dependencies": {
+    "@backbone/design-system": "workspace:*",
+    "@bufbuild/protobuf": "latest",
+    "@connectrpc/connect": "latest",
+    "@connectrpc/connect-web": "latest",
+    "react": "latest",
+    "react-dom": "latest",
+    "react-router": "^7.15.0"
+  },
+  "devDependencies": {
+    "@backbone/design-system-lint": "workspace:*",
+    "@bufbuild/buf": "latest",
+    "@bufbuild/protoc-gen-es": "latest",
+    "@ladle/react": "^5.1.1",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "latest",
+    "oxfmt": "^0.51.0",
+    "oxlint": "^1.66.0",
+    "oxlint-tsgolint": "^0.22.1",
+    "typescript": "^6.0.3",
+    "vite": "latest",
+    "vitest": "^4.0.14"
+  },
+  "packageManager": "pnpm@10.22.0"
+}

package/template/client/packages/design-system/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@backbone/design-system",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "dependencies": {
+    "@backbone/design-system-basic": "workspace:*",
+    "@backbone/design-system-contract": "workspace:*"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0"
+  }
+}

package/template/client/packages/design-system/src/index.ts

@@ -0,0 +1,2 @@
+export * from "@backbone/design-system-basic"
+export type * from "@backbone/design-system-contract"

package/template/client/packages/design-system-basic/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@backbone/design-system-basic",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.tsx",
+      "default": "./src/index.tsx"
+    }
+  },
+  "dependencies": {
+    "@backbone/design-system-contract": "workspace:*"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0"
+  }
+}

package/template/client/packages/design-system-basic/src/button.stories.tsx

@@ -0,0 +1,50 @@
+import type { StoryDefault } from "@ladle/react"
+import { Button, Stack } from "."
+
+export default {
+  title: "Design System / Button",
+} satisfies StoryDefault
+
+export const Primary = () => <Button>Say hello</Button>
+
+export const Secondary = () => <Button variant="secondary">View history</Button>
+
+export const Danger = () => <Button variant="danger">Clear history</Button>
+
+export const DisabledPrimary = () => <Button disabled>Say hello</Button>
+
+export const DisabledSecondary = () => (
+  <Button disabled variant="secondary">
+    View history
+  </Button>
+)
+
+export const DisabledDanger = () => (
+  <Button disabled variant="danger">
+    Clear history
+  </Button>
+)
+
+export const LoadingPrimary = () => <Button loading>Saving...</Button>
+
+export const LoadingSecondary = () => (
+  <Button loading variant="secondary">
+    Opening...
+  </Button>
+)
+
+export const LoadingDanger = () => (
+  <Button loading variant="danger">
+    Clearing...
+  </Button>
+)
+
+export const AllVariants = () => (
+  <Stack gap="sm">
+    <Button>Say hello</Button>
+    <Button variant="secondary">View history</Button>
+    <Button variant="danger">Clear history</Button>
+    <Button disabled>Saved</Button>
+    <Button loading>Saving...</Button>
+  </Stack>
+)

package/template/client/packages/design-system-basic/src/button.tsx

@@ -0,0 +1,26 @@
+import type { ButtonComponent } from "@backbone/design-system-contract"
+
+export const Button: ButtonComponent = ({
+  children,
+  className,
+  disabled,
+  loading = false,
+  type = "button",
+  variant = "primary",
+  ...props
+}) => {
+  const classes = [
+    "ds-button",
+    `ds-button--${variant}`,
+    loading ? "ds-button--loading" : null,
+    className,
+  ]
+    .filter(Boolean)
+    .join(" ")
+
+  return (
+    <button className={classes} disabled={disabled || loading} type={type} {...props}>
+      {children}
+    </button>
+  )
+}

package/template/client/packages/design-system-basic/src/empty-state.stories.tsx

@@ -0,0 +1,18 @@
+import type { StoryDefault } from "@ladle/react"
+import { Button, EmptyState } from "."
+
+export default {
+  title: "Design System / EmptyState",
+} satisfies StoryDefault
+
+export const WithoutAction = () => (
+  <EmptyState description="Say hello to create the first saved input." title="No inputs yet" />
+)
+
+export const WithAction = () => (
+  <EmptyState
+    action={<Button>Say hello</Button>}
+    description="Create a saved hello-world input."
+    title="No inputs yet"
+  />
+)

package/template/client/packages/design-system-basic/src/empty-state.tsx

@@ -0,0 +1,17 @@
+import type { EmptyStateComponent } from "@backbone/design-system-contract"
+import { Heading } from "./heading"
+import { Stack } from "./stack"
+import { Text } from "./text"
+
+export const EmptyState: EmptyStateComponent = ({ action, description, title }) => {
+  return (
+    <section className="ds-empty-state">
+      <Stack gap="sm">
+        <Heading level={2}>{title}</Heading>
+        <Text tone="muted">{description}</Text>
+      </Stack>
+
+      {action && <div className="ds-empty-state__actions">{action}</div>}
+    </section>
+  )
+}

package/template/client/packages/design-system-basic/src/form-field.stories.tsx

@@ -0,0 +1,15 @@
+import type { Story, StoryDefault } from "@ladle/react"
+import { FormField, TextInput } from "."
+
+export default {
+  title: "Design System / FormField",
+} satisfies StoryDefault
+
+export const Default: Story<{ label: string }> = ({ label }) => (
+  <FormField inputId="ladle-field" label={label}>
+    <TextInput id="ladle-field" placeholder="Field input" />
+  </FormField>
+)
+Default.args = {
+  label: "Field label",
+}

package/template/client/packages/design-system-basic/src/form-field.tsx

@@ -0,0 +1,10 @@
+import type { FormFieldComponent } from "@backbone/design-system-contract"
+
+export const FormField: FormFieldComponent = ({ children, inputId, label }) => {
+  return (
+    <label className="ds-field" htmlFor={inputId}>
+      <span className="ds-field__label">{label}</span>
+      {children}
+    </label>
+  )
+}

package/template/client/packages/design-system-basic/src/form.stories.tsx

@@ -0,0 +1,27 @@
+import type { Story, StoryDefault } from "@ladle/react"
+import type { FormEvent } from "react"
+import { Button, Form, FormField, Heading, Inline, Stack, TextInput } from "."
+
+export default {
+  title: "Design System / Form",
+} satisfies StoryDefault
+
+export const Default: Story = () => (
+  <Form ariaLabelledBy="ladle-form-title" onSubmit={preventSubmit}>
+    <Stack gap="md">
+      <Heading id="ladle-form-title" level={3}>
+        Form
+      </Heading>
+      <FormField inputId="ladle-form-name" label="Name">
+        <Inline>
+          <TextInput id="ladle-form-name" placeholder="World" />
+          <Button type="submit">Submit</Button>
+        </Inline>
+      </FormField>
+    </Stack>
+  </Form>
+)
+
+function preventSubmit(event: FormEvent<HTMLFormElement>) {
+  event.preventDefault()
+}

package/template/client/packages/design-system-basic/src/form.tsx

@@ -0,0 +1,9 @@
+import type { FormComponent } from "@backbone/design-system-contract"
+
+export const Form: FormComponent = ({ ariaLabelledBy, children, onSubmit }) => {
+  return (
+    <form aria-labelledby={ariaLabelledBy} className="ds-form" onSubmit={onSubmit}>
+      {children}
+    </form>
+  )
+}