Nordcraft

Create highly performant web apps with SSR, branching, version control, components, and much more! Visit nordcraft.com to learn more.

Discord | BlueSky | YouTube | LinkedIn

Introduction

This repository holds different packages that are used internally by the Nordcraft framework. The packages that are currently available are:

• core 👈 holds core (shared) logic, data models, formula evaluation, and styling used by the other packages
• runtime 👈 includes logic for hydrating, running, and updating a Nordcraft application on the front-end
• ssr 👈 holds server-side rendering, HTML generation, and routing logic
• lib 👈 holds all builtin formulas and actions used by the runtime and during SSR
• search 👈 holds all issue rules, validators, and search functionality for traversing a Nordcraft project
• schemas 👈 holds validation schemas (powered by Valibot) for components, pages, workflows, and actions
• css-parser 👈 the CSS parser used in the Nordcraft editor to power the style panel
• backend 👈 full server runtime implementation using Hono, supporting Cloudflare Workers, Node.js, and Bun for serving and self-hosting Nordcraft applications
• editor 👈 shared editor interfaces, element definitions, and WebRef schemas

All published packages support clean ESM imports directly from their package roots and subpaths:

import { applyFormula } from '@nordcraft/core'
import { ComponentSchema } from '@nordcraft/schemas'
import { renderPageBody } from '@nordcraft/ssr'
import { actions, formulas } from '@nordcraft/std-lib'
import { findProblems } from '@nordcraft/search'
import { createRoot } from '@nordcraft/runtime'

Requirements

Install using bun by running bun install

Commands

• Install dependencies: bun install
• Lint: bun lint
• Format code: bun run prettier:write
• Check types: bun typecheck
• Build: bun run build <-- builds all packages
• Run unit tests: bun test
• Run runtime benchmark: bun run benchmark:runtime
• Run SSR benchmark: bun run benchmark:ssr:run
• Run issues benchmark: bun run benchmark:issues
• Run benchmark unit tests: bun run test:benchmarks

SSR performance in PRs

The SSR benchmark workflow runs on pull requests that change packages/core/**, packages/ssr/**, the shared benchmark code, or the benchmark runner. It builds a worktree for the PR base, runs persistent Bun workers for both revisions, and compares interleaved samples using the same statistics and verdicts as the runtime benchmark.

• Workflow: .github/workflows/ssr_benchmark.yml
• Cases included:
  • core.applyFormula (complex mix, 3k evals)
  • ssr.renderPageBody (collections hot path)
  • ssr.renderPageBody (example project HomePage)
• Samples are reported as milliseconds per operation. --repeat controls how many case executions are included in each measured sample.
• Heap usage is reported alongside timing. The worker forces garbage collection before and after each sample and records the retained process heap delta per execution, so regressions and improvements are shown next to the timing verdict.
• Reports contain median/IQR values, a 95% bootstrap confidence interval, a Welch p-value, and a shared regression verdict.
• A regression is reported only when it is statistically significant and exceeds both the percentage and absolute thresholds.

To run the full comparison locally:

bun bin/runSsrBenchmarks.ts \
  --base-ref=origin/main \
  --runs=25 \
  --warmup=5 \
  --repeat=15 \
  --output-dir=/tmp/ssr-benchmark-data

The runner writes raw samples to head/*.json and base/*.json, plus ssr-benchmark-report.md and ssr-benchmark-report.json. Use --export-markdown=... and --export-json=... to choose the report paths. The default comparison uses --base-ref=origin/main; pass --base-ref= with --skip-build=true for a head-only run. Head-only results are labeled A/A mode rather than byte-identical. Use --keep-worktree=true while debugging worktree setup.

Useful comparison options:

• --runs=20 (measured samples per case; default)
• --warmup=4 (warmup samples per case; default)
• --repeat=1 (executions per measured sample; default)
• --max-regression-percent=3.0 --max-regression-ms=1.0
• --noise-threshold-percent=1.5
• --fail-on-regression=false (generate a report without failing the process)

Status

While we consume all packages internally in the Nordcraft framework, this project is currently in development and is not yet ready for other applications to consume.

Plan

As announced in July '24, Nordcraft is in the process of going fully open source. The goal is to move more and more code into this repository and make it possible to self host a Nordcraft application.

We're currently working on moving more of the server-side rendering logic into this repository. This means that most updates are going to be in the ssr package for the time being.

Dependencies

The dependencies between the packages are as follows:

• core is a dependency for all other packages
• schemas is a dependency for search
• ssr is a dependency for search and backend
• std-lib is a dependency for runtime, ssr, and backend
• runtime assets are synced and served by backend

Releases

We use GitHub releases and release to npm atm, which is where we consume packages from internally.

To release a new version to npm:

1. Update the version in the root package.json file
2. Create a PR
3. Once the PR is merged, it will automatically release all packages to npm

Contributing

If you find a bug or have an idea for a new feature, please open an issue. We also welcome pull requests. We are actively monitoring this repository.

If you have any questions, feel free to ask them in our Discord or reach out by e-mail

Local development

To consume all packages locally, it's useful to run bun run link in the root of the repository. This will use bun link on all packages in the repository.

Other than that, the best way to test atm is to use the hono example.

Documentation

The Nordcraft docs are open source.

If you'd like to contribute to the documentation, view all open issues on GitHub, or open an issue if you find something wrong or missing.

View the Nordcraft official documentation.