Norq

Quickstart

Notifications as code. AI-native by architecture.

Norq is a code-first notification framework: write Markdown templates once and compile them to six channels — email, SMS, push, Slack, WhatsApp, and MS Teams — from one project. One shared schema and one brand.yaml keep the data contract and visual identity consistent across every channel.

Type-safe SDKs for TypeScript, Python, Go, Java, and Ruby fail at compile time instead of in production. The compiler doubles as an MCP server, so Claude Code, Codex, or Cursor get a compiler they can call, a schema they can read, and a strict-mode validator that catches the typoed paths LLMs produce.

A public registry lets you norq add welcome to drop in a working multi-channel notification — schema, samples, and tests included — or publish partials and brand presets your own teams reuse. Bring an agent into the loop or don’t — the architecture is the same.

  • Write what you know. It’s Markdown. No JSX, no DSL, no framework lock-in.
  • One project, six channels. Email, SMS, push, Slack, WhatsApp, Teams. Same data contract, same syntax, same CI pipeline.
  • One brand, every channel. Define your colors, typography, and named styles once in brand.yaml — DTCG-2025.10 tokens, dark mode, round-trip with Figma and Style Dictionary. Templates reference tokens by name (color="brand", bg="card"); per-template overrides and runtime tenant overrides are supported when you need them (whitelabeling).
  • Style with confidence. Named tokens (size="lg", color="brand") guarantee cross-client safety. No more “it works in Chrome but breaks in Outlook.”
  • Build components. Parameterized partials let you create reusable patterns — product cards, stats rows, pricing tables — without code.
  • Type-safe from schema to send(). Define your data shape once in data.schema.yaml, then generate typed SDK bindings for TypeScript, Python, Go, Java, or Ruby. Every send() call gets IDE autocomplete and compile-time validation — no more guessing field names or passing wrong shapes at runtime.
  • Catch bugs before send. Strict mode is on by default — typoed paths ({{user.nam}}), unknown pipes (uppercse), and wrong-typed pipe args fail loudly instead of silently rendering as empty strings.
  • Ship with certainty. Schema validation, null-safety linting, deliverability checks, spam scoring, and a testing framework — all built in. Ten built-in providers (Resend, SendGrid, Twilio, Bird, FCM, APNs, Expo, Web Push, SuprSend, Console) plus custom HTTP providers for anything else.
  • AI-native authoring. Pair Norq with Claude Code, Codex, Cursor, or any MCP-compatible agent. The Norq plugin ships an MCP server (12 tools that call the real compiler — norq_resolve, norq_compile, norq_lint, norq_render_preview, …) plus an agentskills.io skill that teaches the agent the schema-first workflow, every directive and pipe, brand tokens, and channel rules. norq brand sync-agents keeps AGENTS_BRAND.md in lockstep with your brand.yaml. Drop https://norq.sh/llms-full.txt into any chat for a full syntax reference. Result: agents iterate against ground truth instead of guessing.
  • Formally specified. Norq has a conformance spec with hundreds of embedded tests — the compiler is validated against the spec on every commit. If you need to know exactly how something compiles, the spec is the definitive answer.

Try it in the browser → — no install needed.

Install

Coming soon. Package registry distribution is not yet available. See norq.sh for updates. To build from source, see Contributing.

Build your first notification

Ready for the full walkthrough? The Tutorial takes you end-to-end: scaffold a project, define a schema, write templates for multiple channels, lint and test, generate type-safe bindings, and ship a real send() call.

norq init --example

Then follow the Tutorial.

Notification types

Norq organizes notifications into three required type folders:

Type Folder When to use
System notifications/system/ Always delivered — password resets, security alerts
Transactional notifications/transactional/ Always delivered — order confirmations, shipping updates
Promotional notifications/promotional/ Subject to user preferences — digests, campaigns

Editor support

  • VS Code — install the Norq extension for diagnostics, completions, hover, and inline channel previews (Cmd+K V)
  • Zed — install norq from the extension registry
  • Any LSP editor — run norq lsp as a language server

Where to go next

  • Tutorial — build your first notification end-to-end
  • Brand — design tokens, dark mode, named styles
  • Templates — directives, expressions, control flow, partials
  • Channels — per-channel guides
  • Providers — configure delivery
  • SDKs — Node, Python, Go, Java, Ruby
  • CLI reference — all commands and flags