Self-hosting

By default, Nordcraft hosts your websites on Nordcraft's infrastructure. Because Nordcraft is open source, you can also export your project and self-host it on your own infrastructure using the open-source backend package in the Nordcraft GitHub repository.

Info

The Nordcraft self-hosting backend package is still under active development. Check the Nordcraft repository on GitHub for the latest updates and improvements.

What is included

When you self-host a Nordcraft website with the @nordcraft/backend package, your site runs with the core features you get on Nordcraft's hosting:

  • Server-side rendering (SSR): Pages are rendered on the server for fast initial load times and search engine optimization (SEO), then hydrated in the browser for interactivity.
  • Custom formulas and actions: Your project's custom formulas and actions work during both server-side rendering and in the browser.
  • Redirects and proxies: Handles the redirects and proxies configured in your project.
  • API requests and cookies: Proxies client API requests and supports HTTP-only cookies for authentication.
  • Fonts and site files: Serves Google Fonts, page stylesheets, exported custom elements, /sitemap.xml, /robots.txt, /manifest.json, and /favicon.ico based on your project configuration.

Before you start

To self-host a Nordcraft website, you need:

  • A Nordcraft website project that you want to host
  • Bun installed on your computer to install dependencies and prepare your project
  • A hosting provider if you plan to publish online, such as Cloudflare Workers, Docker, or a server running Bun or Node.js

Export and set up your project

Follow these steps to export your website from Nordcraft and add it to the backend package:

  1. 1
    Open your project in Nordcraft and go to the Project details page.
  2. 2
    Find the branch you want to host (usually main), open its actions menu, and select Download branch to save your project as a JSON file.
  3. 3
    Clone the Nordcraft repository from GitHub, install the dependencies, and build the workspace packages from the root folder:
bash
  1. 4
    Move the JSON file you downloaded from Nordcraft into packages/backend/__project__/project.json, replacing the example project.json file.
Tip

Your self-hosted site serves the snapshot you exported in project.json. Whenever you publish new changes in Nordcraft, download the updated branch, replace project.json, and redeploy.

Run locally

Before deploying to a live server, you can test your self-hosted website locally. Navigate to the backend folder and start the development server:

bash

This prepares your project's pages and static assets and starts a local server so you can preview your site in your browser.

If you want to test the compiled production server locally, you can also run it directly with Bun (bun run bunrun) or Node.js (bun run noderun).

Deploy your website

Once your project is set up in packages/backend, you can deploy it to Cloudflare Workers or package it with Docker to run on any server.

Deploy to Cloudflare Workers

The backend package comes pre-configured for Cloudflare Workers in packages/backend/wrangler.toml.

  1. 1
    Provide your Cloudflare account ID by setting the CLOUDFLARE_ACCOUNT_ID environment variable or adding it to packages/backend/wrangler.toml.
  2. 2
    Deploy your website from the packages/backend folder:
bash

This command prepares your project's static assets, bundles the application, and publishes it to Cloudflare Workers.

Deploy with Docker

If you want to host your website on your own server or any container platform, use the included Dockerfile to build and run a lightweight container.

From the packages/backend folder, run:

bash

By default, the container serves your website on port 3000.

Best practices

Keep the following in mind when running a self-hosted Nordcraft website:

  • Use HTTPS in production: Serve your public website over HTTPS so features like HTTP-only cookies work properly in browsers.
  • Keep secrets out of your project: Never store private API keys or sensitive credentials in your Nordcraft project. Read the Security guide to learn how to handle sensitive data safely.
  • Keep your export in sync: Self-hosted websites do not automatically update when you edit your project in Nordcraft. Re-export your branch and redeploy whenever you want changes to go live.
Edit article
Help Forum