Define collections and fields in one TypeScript config. Valence derives the database tables, admin UI, REST API, typed frontend scaffold, entity codegen, page routing, first-party analytics, validators, and migrations from that single schema. No plugins. No vendor scripts. Minimal, audited dependencies.

// valence.config.ts
import { defineConfig, collection, field } from '@valencets/valence'

export default defineConfig({
  db: {
    host: process.env.DB_HOST ?? 'localhost',
    port: Number(process.env.DB_PORT ?? 5432),
    database: process.env.DB_NAME ?? 'mysite',
    username: process.env.DB_USER ?? 'postgres',
    password: process.env.DB_PASSWORD ?? ''
  },
  server: { port: Number(process.env.PORT ?? 3000) },
  collections: [
    collection({
      slug: 'posts',
      labels: { singular: 'Post', plural: 'Posts' },
      fields: [
        field.text({ name: 'title', required: true }),
        field.slug({ name: 'slug', slugFrom: 'title', unique: true }),
        field.richtext({ name: 'body' }),
        field.boolean({ name: 'published' }),
        field.date({ name: 'publishedAt' })
      ]
    }),
    collection({
      slug: 'users',
      auth: true,
      fields: [
        field.text({ name: 'name', required: true }),
        field.select({ name: 'role', defaultValue: 'editor', options: [
          { label: 'Admin', value: 'admin' },
          { label: 'Editor', value: 'editor' }
        ]})
      ]
    })
  ],
  admin: { pathPrefix: '/admin', requireAuth: true },
  telemetry: {
    enabled: true,
    endpoint: '/api/telemetry',
    siteId: 'mysite'
  }
})

That config gives you: posts and users tables in Postgres, a server-rendered admin panel with form validation and session auth (Argon2id), a REST API at /api/posts and /api/users, a typed src/ scaffold with entity interfaces and API clients, Zod validators, database migrations, and a first-party analytics pipeline that tracks user intent without any third-party scripts on your public pages. Change the schema, everything follows.

Quick Start

npx @valencets/valence init my-site
cd my-site
pnpm dev

The init wizard walks you through:

• Database -- name, user, password (creates the DB and runs migrations)
• Admin user -- email + password for the admin panel (role set to admin)
• Seed data -- optional sample post to start with
• Framework -- plain HTML templates, Astro, or bring your own
• Git -- initializes a repo with the first commit

Init also generates a src/ directory with Feature-Sliced Design structure, typed entity interfaces, and API clients derived from your collections. Pass --yes to skip prompts and accept defaults (useful for CI).

Open http://localhost:3000/admin to sign in. Open http://localhost:3000 for the landing page.

What You Get

• Database tables derived from your field definitions. UUID primary keys, timestamps, soft deletes.
• Admin panel at /admin. Server-rendered HTML forms, CSRF protection, session auth with Argon2id. Login page with proper error handling.
• REST API at /api/:collection. CRUD with Zod validation, parameterized queries, Result<T, E> error handling.
• Migrations generated from schema diffs. Deterministic SQL, idempotent, version-tracked.
• 18 field types. text, textarea, richtext, number, boolean, select, date, slug, media, relation, group, email, url, password, json, color, multiselect, array.
• Rich text editor. Lexical-powered editor in the admin panel with heading, list, blockquote, link, and code formatting.
• FSD scaffold. valence init generates src/ with Feature-Sliced Design: app/, pages/, entities/, features/, shared/.
• Entity codegen. Typed interfaces + API clients generated from your schema. // @generated files regenerate on config change; user-edited files are never overwritten.
• Static file serving. public/ served with MIME types and path traversal protection.
• Page routing. src/pages/ maps to URL paths. List + detail page templates scaffold per collection.
• Config watcher. Edit valence.config.ts during dev and entity types and API clients regenerate automatically.
• Admin headTags. Inject custom <link>, <meta>, <script> tags into the admin <head> via config.
• First-party analytics. Built-in telemetry that runs entirely in your Postgres -- no vendor scripts, no third-party dashboards, no data leaving your infrastructure.
• Learn mode. Interactive 6-step tutorial embedded in valence dev that teaches core concepts through real actions. Run valence init --learn to try it.

Telemetry

Valence includes a complete, privacy-respecting analytics pipeline that runs entirely on your own infrastructure. No Google Analytics, no Plausible, no third-party scripts on your public pages. Your data stays in your Postgres.

How it works:

1. Annotate HTML elements with data-telemetry-* attributes:

   <button data-telemetry-type="CLICK" data-telemetry-target="hero.cta">
     Get Started
   </button>

2. The client library captures user intent events in a pre-allocated ring buffer (zero allocation in the hot path) and auto-flushes via navigator.sendBeacon() every 30 seconds.

3. The server ingests beacon payloads, stores raw events, and aggregates them into daily summaries -- sessions, pageviews, conversions, top pages, top referrers, device breakdowns.

4. View it all in the built-in analytics dashboard at /admin/analytics.

11 intent types beyond simple pageviews: CLICK, SCROLL, VIEWPORT_INTERSECT, FORM_INPUT, INTENT_NAVIGATE, INTENT_CALL, INTENT_BOOK, INTENT_LEAD, LEAD_PHONE, LEAD_EMAIL, LEAD_FORM. This means you can track conversion-oriented actions (calls, bookings, form submissions) natively, not just clicks.

Architecture: The telemetry pipeline spans two packages. @valencets/core handles client-side capture (ring buffer, event delegation, beacon flush). @valencets/telemetry handles server-side ingestion, validation, daily aggregation, and query functions (getDailyTrend, getDailyBreakdowns). The CMS admin panel consumes these queries to render the dashboard.

Packages

| Package | What it does | External deps | |---------|-------------|---------------| | @valencets/ui | 18 Web Components. ARIA, i18n, telemetry hooks, hydration directives. OKLCH design tokens. | none | | @valencets/core | Router + server. pushState nav, fragment swaps, prefetch, view transitions, server islands. | neverthrow | | @valencets/db | PostgreSQL query layer. Tagged template SQL, parameterized queries, Result<T,E>, migration runner. | postgres, neverthrow, zod | | @valencets/cms | Schema engine. collection() + field.* produces tables, validators, REST API, admin UI, auth, media. Rich text via Lexical. | lexical, argon2, zod, neverthrow | | @valencets/telemetry | Beacon ingestion, event storage, daily summaries, fleet aggregation. | postgres, neverthrow | | @valencets/valence | CLI + FSD scaffold + entity codegen. valence init, valence dev, valence migrate, valence build. | tsx, zod, neverthrow |

Total external runtime deps: 6 — postgres, neverthrow, zod, lexical, argon2, tsx. All MIT-licensed, all audited via Socket.

Browser JS: Public-facing pages ship zero third-party JavaScript. The admin panel uses Lexical (Meta, MIT, ~40kB gzipped) for rich text editing only.

Non-Negotiable

| Rule | Why | |------|-----| | Complexity < 20 | Every function fits on one screen. No exceptions. | | Result<T, E> everywhere | If it can fail, the type signature says so. Both branches handled or it doesn't compile. | | 14kB critical shell | First paint in the first TCP data flight. CDN-ready with cache profiles and server islands. | | Pre-allocated ring buffer | Zero allocation in the telemetry hot path. | | Zero third-party JS on public pages | Your site ships your code. Lexical is admin-only. Nothing phones home. | | 1,547 tests | Strict TypeScript, neostandard, CI on every push. |

Documentation

• Getting Started
• Architecture
• CMS Guide
• Developer Guide
• Troubleshooting

Contributing

git clone https://github.com/valencets/valence.git
cd valence
pnpm install
pnpm build
pnpm test

See CONTRIBUTING.md for standards and the TDD workflow.

License

MIT