Nordcraft Engine

The @nordcraft/ssr package provides the server-side logic required by the Nordcraft framework. It is primarily used for server-side rendering (SSR) of Nordcraft pages, managing project bundling, and resolving references within formulas and actions.

Key capabilities include:

• Server-Side Rendering (SSR): Rendering Nordcraft pages on the server to improve initial load performance and SEO.
• Reference Resolution: Finding and resolving references within formulas and actions.
• Project Bundling: Splitting projects into granular bundles, typically following a pattern of one bundle per page or component.

The @nordcraft/runtime package is the client-side engine for Nordcraft applications. It manages the core lifecycle of the application, including:

• Rendering: Driving the visual output of the application.
• Event Handling: Processing user and system events.
• State Management: Maintaining the application state throughout its lifecycle.

The @nordcraft/core package provides the foundational logic and shared primitives used across the Nordcraft framework. It is primarily a utility and type-definition package that does not perform high-level orchestration itself, but instead provides the building blocks for other Nordcraft packages.

Key responsibilities include:

• Style Logic: Mechanisms for generating unique hashes and managing element styles.
• Utility Functions: Shared helper functions used throughout the ecosystem.
• Data Structures: Core TypeScript types and interfaces that define the data contracts for the framework.

Nordcraft is a framework for building high-performance web applications with SSR, branching, version control, and components. The repository is organized into several specialized packages:

• @nordcraft/core: Contains shared core logic used by all other packages.
• @nordcraft/runtime: Handles front-end logic for hydrating, running, and updating Nordcraft applications.
• @nordcraft/ssr: Contains server-side rendering logic.
• @nordcraft/std-lib: Provides built-in formulas and actions used by both the runtime and SSR.
• @nordcraft/search: Provides issue rules and project traversal functionality (currently powers the editor's issue panel via a web worker).
• css-parser: A CSS parser used by the Nordcraft editor's style panel.

The @nordcraft/std-lib package provides the standard set of built-in formulas and actions available for use within a Nordcraft project. These primitives allow you to implement logic and behaviors using pre-defined, optimized implementations.

For a complete list of all available formulas and actions, refer to the official Nordcraft documentation:

• Formulas Reference: https://docs.nordcraft.com/references/formulas
• Actions Reference: https://docs.nordcraft.com/references/actions

If you are developing across multiple packages within this repository and want them to reference each other locally, run the following command in the root directory. This utilizes bun link to link all internal packages together.

bun run link

Nordcraft uses bun for dependency management and task execution. Use the following commands to manage the repository:

• Install dependencies: bun install
• Lint code: bun lint
• Check TypeScript types: bun typecheck
• Build all packages: bun run build

The preview command runs a preview server that fetches project files from a Durable Object running on internal Nordcraft services.

To use this command, you must first create a symlink to the internal Nordcraft repository using the preview-link command:

1. bun run preview-link <path-to-nordcraft-internal>
2. bun run preview

To install the Nordcraft backend dependencies, run the installation command from the root of the project using bun.

bun install

The deploy command deploys the backend to Cloudflare Workers. It includes a predeploy hook that synchronizes static files into assets/_static.

Configuration Requirement: Since the wrangler.toml file does not include an account ID, you must either:

1. Provide the CLOUDFLARE_ACCOUNT_ID environment variable.
2. Manually modify the wrangler.toml file to include your account ID.

bun run deploy

To test the custom element implementation, you must first start the Hono server environment. This provides the necessary backend/template context for the example to function.

1. Run the development server using bun with the template environment variable set to medium:

   template=medium bun run dev

2. Once the server is running, open the custom-element.html file directly in your browser.
3. Verify that the custom element renders correctly and that its interactive features are functional.