@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, GraphQL endpoint, typed frontend scaffold, entity codegen, page routing, first-party analytics, validators, and migrations from that single schema. No plugins required. 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' },
      versions: { drafts: true },
      hooks: {
        afterChange: [({ doc }) => console.log('saved', doc.id)]
      },
      fields: [
        field.text({ name: 'title', required: true }),
        field.slug({ name: 'slug', slugFrom: 'title', unique: true }),
        field.richtext({ name: 'body' }),
        field.tabs({
          tabs: [
            {
              label: 'Details',
              fields: [
                field.boolean({ name: 'published' }),
                field.date({ name: 'publishedAt', condition: (data) => data.published === 'true' })
              ]
            },
            {
              label: 'SEO',
              fields: [
                field.text({ name: 'metaTitle' }),
                field.textarea({ name: 'metaDescription' })
              ]
            }
          ]
        })
      ]
    }),
    collection({
      slug: 'users',
      auth: true,
      fields: [
        field.text({ name: 'name', required: true }),
        field.select({
          name: 'role',
          defaultValue: 'editor',
          access: { update: ({ user }) => user.role === 'admin' },
          options: [
            { label: 'Admin', value: 'admin' },
            { label: 'Editor', value: 'editor' }
          ]
        })
      ]
    })
  ],
  routes: [
    {
      path: '/blog/:slug',
      collection: 'posts',
      type: 'detail',
      loader: async ({ params, pool }) => {
        const post = await pool`SELECT * FROM posts WHERE slug = ${params.slug}`
        return { data: { post: post[0] } }
      }
    },
    {
      path: '/contact',
      method: 'POST',
      action: async ({ body }) => {
        // handle form submission
        return { redirect: '/thank-you' }
      }
    }
  ],
  onServer ({ server, pool, cms, registerRoute }) {
    registerRoute('GET', '/api/health', (_req, res) => {
      res.writeHead(200).end('ok')
    })
  },
  admin: { pathPrefix: '/admin', requireAuth: true },
  graphql: 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 GraphQL endpoint at /graphql, typed routes with loaders and actions, an onServer hook for custom routes and WebSocket handlers, a typed src/ scaffold with entity interfaces and API clients, Zod validators, database migrations, draft versioning with revision history, 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

Schema Engine

• Database tables derived from your field definitions. UUID primary keys, timestamps, soft deletes.
• 22 field types. text, textarea, richtext, number, boolean, select, date, slug, media, relation, group, email, url, password, json, color, multiselect, array, blocks, tabs, row, collapsible.
• Layout fields. Tabs, rows, and collapsible sections for organizing complex admin forms without affecting the database schema.
• Conditional fields. Show or hide fields based on other field values using the condition function. Re-renders via htmx partials.
• Field access control. Per-field create, read, and update access control functions that receive the current user context.
• Field hooks. beforeValidate, beforeChange, afterChange, afterRead hooks on individual fields for data transformation and side effects.
• Collection hooks. 11 lifecycle hooks: beforeValidate, beforeChange, afterChange, beforeRead, afterRead, beforeDelete, afterDelete, beforePublish, afterPublish, beforeUnpublish, afterUnpublish.
• Globals. Single-document configs (site settings, navigation, footer) via global() with the same field system.
• Migrations generated from schema diffs. Deterministic SQL, idempotent, version-tracked.

Admin Panel

• Server-rendered admin at /admin. HTML forms, CSRF protection, session auth with Argon2id. Login page with proper error handling.
• Rich text editor. Tiptap-powered editor (ProseMirror) with heading, list, blockquote, link, code, divider, and code block formatting. Slash command menu for block insertion.
• Draft versioning. Enable versions: { drafts: true } on a collection for publish/unpublish workflow with revision history and diff view.
• Autosave. Automatic draft saving with visual indicator via the <val-autosave> component.
• Live preview. Split-pane editor with real-time preview iframe, communicating via postMessage protocol.
• Bulk operations. Select multiple documents in list view for bulk delete, publish, or unpublish.
• Image processing. Automatic image resizing and optimization via Sharp on media upload.
• Admin headTags. Inject custom <link>, <meta>, <script> tags into the admin <head> via config.

API Layer

• REST API at /api/:collection. CRUD with Zod validation, parameterized queries, Result<T, E> error handling. Bulk endpoint at /api/:slug/bulk.
• GraphQL API. Auto-generated schema from your collections with resolvers wired to the Local API. Enable with graphql: true in config.
• Local API. Programmatic access to all CRUD operations with the same validation, hooks, and access control as the REST layer.
• Full-text search. PostgreSQL tsvector/tsquery with relevance ranking, configurable per collection.

Routing

• Page routing. src/pages/ maps to URL paths. List + detail page templates scaffold per collection.
• Routes with loaders. Define typed routes in config with loader functions that fetch data server-side and inject it into the page.
• Routes with actions. Handle form submissions with action functions that return redirects or field-level errors.
• onServer hook. Access the raw Node.js http.Server, database pool, CMS instance, and registerRoute for custom endpoints, WebSocket upgrade handlers, or middleware.
• Typed route helpers. Auto-generated route types with extractParams for type-safe URL building.
• View transitions. Built-in view transition presets for smooth page navigation.

Frontend

• 23 Web Components. ARIA-compliant, i18n-ready, telemetry hooks, hydration directives. OKLCH design tokens. Zero dependencies.
• Component registration separation. Component classes are defined separately from customElements.define() calls for tree-shaking -- import only what you use.
• 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.
• Config watcher. Edit valence.config.ts during dev and entity types and API clients regenerate automatically.

Security

• Argon2id password hashing for admin authentication.
• CSRF protection on all admin forms.
• Session auth with httpOnly, secure cookie flags and configurable session max age.
• Path traversal protection on static file serving, media uploads, and cloud storage.
• URL redirect validation to prevent open redirect attacks.
• Parameterized SQL everywhere -- no string concatenation in queries.
• CodeQL and Socket auditing in CI.

Plugin System

• First-party plugins. @valencets/plugin-seo (auto-title, meta field injection), @valencets/plugin-nested-docs (tree structures with breadcrumb computation), @valencets/plugin-cloud-storage (S3-compatible object storage).
• Plugin API. Plugins are config transformers -- a function that receives a CmsConfig and returns a modified CmsConfig. Compose with the plugins array.

Analytics

• 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	23 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.	@valencets/resultkit
@valencets/db	PostgreSQL query layer. Tagged template SQL, parameterized queries, Result<T,E>, migration runner.	postgres, @valencets/resultkit, zod
@valencets/cms	Schema engine. collection() + field.* produces tables, validators, REST API, admin UI, auth, media, image processing. Rich text via Tiptap (ProseMirror).	tiptap, argon2, sharp, zod, @valencets/resultkit
@valencets/graphql	Auto-generated GraphQL schema + resolvers from CMS collections.	graphql, @valencets/resultkit
@valencets/telemetry	Beacon ingestion, event storage, daily summaries, fleet aggregation.	postgres, @valencets/resultkit
@valencets/valence	CLI + FSD scaffold + entity codegen + route types. valence init, valence dev, valence migrate, valence build.	tsx, zod, @valencets/resultkit
@valencets/plugin-seo	SEO field injection and auto-title hook.	none (peer dep on cms)
@valencets/plugin-nested-docs	Tree structures with breadcrumb computation.	none (peer dep on cms)
@valencets/plugin-cloud-storage	S3-compatible media storage adapter.	@aws-sdk/client-s3, @valencets/resultkit

Core external runtime deps: 8 -- postgres, @valencets/resultkit, zod, tiptap, argon2, sharp, graphql, tsx. All MIT-licensed, all audited via Socket.

Browser JS: Public-facing pages ship zero third-party JavaScript. The admin panel uses Tiptap (ProseMirror, MIT) 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. Tiptap is admin-only. Nothing phones home.
3,022 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