@valencets/valence

Schema-driven full-stack framework for Node.js and PostgreSQL.

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:

• Annotate HTML elements with data-telemetry-* attributes:

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

• 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.

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

• 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