Registry

The Norq registry is a curated library of production-ready notification templates. Import a working welcome email, password reset, invoice, or any other common notification in seconds -- no boilerplate, no guesswork.

norq add welcome

Templates are source code you own. Edit freely after importing -- there is no lock-in.

Why use the registry

• Skip the blank page. Get a tested, multi-channel notification with schema, samples, and assertions already wired up.
• Best practices baked in. Templates follow Norq conventions: null guards on optional fields, proper directive usage, deliverability-safe HTML structure.
• Consistent patterns across teams. Shared registries give every team the same starting point for common notifications.
• Community sharing. Publish your own templates to a custom registry for your organization or the community.

Quick start

Start with a fresh project and add a template:

norq init
norq add welcome

Before:

notifications/
  system/
  transactional/
  promotional/

After:

notifications/
  _shared/
    email-footer.md
  transactional/
    welcome/
      email.md
      sms.md
      slack.md
      push.md
      data.schema.yaml
      data.samples.yaml
      tests.yaml

The imported notification is ready to compile and send. Dependencies (partials referenced by {{> name}}) are auto-resolved and installed to _shared/.

norq compile transactional/welcome --channel email --json
norq send transactional/welcome --to '{"email":"user@example.com"}' --sample "Default"

Browsing templates

Web

Browse the official registry at norq.sh/r/. Each template has a detail page with channel previews, schema documentation, and a one-click import button.

The playground toolbar includes an Import button that pulls registry templates directly into the browser editor.

CLI

Search by keyword:

norq registry search welcome
norq registry search invoice --type transactional
norq registry search --category account

List everything available:

norq registry list
norq registry list --type promotional --json

Inspect a specific template before importing:

norq registry view welcome
norq registry view welcome --files --json

Importing templates

Bare name

Import from the official registry:

norq add welcome

Named registry

Import from a custom registry namespace:

norq add @acme/invoice

GitHub shorthand

Import directly from a Git repository:

norq add github:user/repo/notifications/transactional/welcome

Pin to a specific ref:

norq add github:user/repo/notifications/transactional/welcome@v1.0

Multiple items

Import several templates at once:

norq add welcome password-reset magic-link

Flags

Preview before committing:

norq add welcome invoice --dry-run

Dependency resolution

Registry items declare their dependencies in the registryDependencies field of item.json. When you run norq add, the resolver:

1. Recursively fetches all transitive dependencies (dependencies of dependencies).
2. Topologically sorts them using Kahn's algorithm -- dependencies are written before dependents.
3. Detects circular dependencies and reports them as errors.

Partials are installed to the notification-local _shared/ directory. Existing partials with the same name are not overwritten unless --overwrite is passed.

# Dry-run to see the full dependency tree before writing:
norq add welcome --dry-run

After importing

Templates are yours. Edit the markdown, change the data schema, adjust the copy.

Run the standard workflow to verify everything works:

norq lint                                              # check for issues
norq compile transactional/welcome --channel email \
  --sample "Default" --json                            # preview output
norq test                                              # verify assertions pass

Imported templates use your project's theme automatically. Customize colors, fonts, and layout in norq.config.yaml:

theme:
  brandColor: "#7c3aed"
  buttonColor: "#7c3aed"
  fontFamily: "Inter, sans-serif"

See Project Configuration for all theme options.

Custom registries

Configure named registries in norq.config.yaml. Each namespace maps to a URL pattern where {name} is replaced with the item name at fetch time.

URL string form

registries:
  "@acme": "https://registry.acme.com/r/{name}.json"
  "@oss": "https://templates.example.org/r/{name}.json"

norq add @acme/welcome fetches https://registry.acme.com/r/welcome.json.

Authenticated registries

For private registries, use the object form with url and headers:

registries:
  "@private":
    url: "https://internal.company.com/r/{name}.json"
    headers:
      Authorization: "Bearer ${REGISTRY_TOKEN}"

Headers support ${ENV_VAR} expansion. The environment variable must be set at runtime or norq doctor will report an error.

Default registry

Bare names (norq add welcome) always resolve against the official registry at norq.sh/r/. Named registries only handle their own namespace prefix.

Authoring a registry

Build and host your own registry for internal templates, team standards, or community sharing.

Registry structure

A registry is a directory with a registry.json manifest and item directories:

my-registry/
  registry.json
  notifications/
    welcome/
      item.json
      email.md
      sms.md
      data.schema.yaml
      data.samples.yaml
      tests.yaml
  partials/
    email-footer/
      item.json
      email-footer.md
  themes/
    brand-dark/
      item.json
      theme.yaml

Registry manifest

registry.json declares metadata and lists items:

{
  "name": "acme-templates",
  "description": "Internal notification templates for Acme Corp",
  "items": [
    "notifications/transactional/welcome",
    "partials/email-footer",
    "themes/brand-dark"
  ]
}

Item metadata

Each item directory contains an item.json with metadata:

{
  "name": "welcome",
  "description": "Welcome email with onboarding steps",
  "type": "notification",
  "channels": ["email", "sms", "slack", "push"],
  "categories": ["transactional"],
  "registryDependencies": ["email-footer"]
}

Build and validate

Generate the static JSON files that norq add fetches at runtime:

norq registry build                    # outputs to ./registry-out/
norq registry build --out dist/r       # custom output directory

Validate the manifest and all items before publishing:

norq registry validate

Deploy

The built output is static JSON. Host it anywhere:

• GitHub Pages -- push registry-out/ to a gh-pages branch
• Cloudflare Pages / Vercel -- point the build output directory
• S3 / GCS -- upload the directory with public read access
• Any static file server -- serve the directory over HTTPS

Configure consumers to point at your hosted URL:

registries:
  "@acme": "https://acme-templates.pages.dev/r/{name}.json"

Item types

The registry supports three item types:

Import any type the same way:

norq add welcome              # notification
norq add email-footer         # partial
norq add brand-dark           # theme