How to Install EmDash and Get Your First Site Running

By Seahawk November 15, 2026 6 min read

To install EmDash, run npm create emdash@latest, answer five prompts, start the dev server and finish the setup wizard at /_emdash/admin/. Choose Node.js as the deploy target and you need no cloud account: the site runs on your own machine with a SQLite database and local file storage. This guide follows the official steps for EmDash 1.5, the current release in November 2026, and adds the details that trip people up on a first install.

Still deciding whether EmDash is the right CMS? Start with our EmDash vs WordPress comparison.

Before you start

  • Node.js 22.23.4 or later. Check with node --version. Odd-numbered releases such as Node 23 are not supported by Astro, which EmDash is built on.
  • A package manager. npm, pnpm, yarn and bun all work.
  • A browser that supports passkeys. EmDash signs you in with a passkey by default, so there is no password to choose.

Step 1: Scaffold the site

npm create emdash@latest

The equivalents are pnpm create emdash@latest, yarn create emdash and bun create emdash@latest. The scaffolder asks these questions:

PromptOptionsWhat to pick first time
Project nameAny folder name, or . for the current foldermy-emdash-site
Where will you deploy?Cloudflare Workers (D1 and R2) or Node.js (SQLite and local file storage)Node.js
Which template?Blog, Starter, Marketing, PortfolioStarter
Which package manager?pnpm, npm, yarn, bunThe one you ran the command with
Install dependencies?Yes or NoYes

If you choose Cloudflare Workers, there is one more question: whether to enable sandboxed plugins. That feature needs a Worker Loader binding, which is available on Workers paid plans, so the default is off.

The deploy target matters more than it looks. It decides which template variant you get, including the database adapter and config files, so pick the platform you really plan to host on. The templates differ like this:

  • Starter: a general-purpose site with posts and pages.
  • Blog: posts, pages and authors.
  • Marketing: landing pages and calls to action.
  • Portfolio: projects and case studies.

To skip the prompts, for example in a script, pass flags:

npm create emdash@latest my-blog -- --template blog --platform node --pm npm --yes

Be careful with --yes on its own. Any option you leave out falls back to the defaults, which are Cloudflare and the Blog template.

Step 2: Start the dev server

cd my-emdash-site
npm run dev

Astro prints the local address, normally http://localhost:4321/. Keep this terminal open while you work.

Step 3: Run the setup wizard

  1. Open http://localhost:4321/_emdash/admin/. A new site redirects to the setup wizard.
  2. Enter a site title and, if you like, a tagline. Leave Include sample content selected so you have a Welcome post and an About page to experiment with.
  3. Enter your email address and name.
  4. Register a passkey when the browser asks, using your fingerprint, face or device PIN.
  5. Select Open the dashboard.

You are now in the admin, with Posts and Pages in the navigation.

Step 4: Publish your first edit

  1. Open Posts, then the Welcome post.
  2. Change the title and select Save. This saves a draft; visitors still see the old version.
  3. Select Publish changes.
  4. Reload http://localhost:4321/ in another tab. The new title is on the home page.

There was no rebuild in between. EmDash pages read published content from the database when they are requested.

What the scaffolder created

An EmDash site is a normal Astro project with the CMS added as an integration. These are the files worth knowing:

FileWhat it does
astro.config.mjsTurns on server rendering, the Node.js adapter and React (the admin is a React app), and tells EmDash which database and media folder to use
src/live.config.tsConnects EmDash content to Astro's live content collections
src/pages/index.astroThe home page, which queries the posts collection
seed/seed.jsonDefines the starting collections, fields and sample content
.envHolds EMDASH_ENCRYPTION_KEY, generated for you and ignored by Git

The home page query is short enough to read in full, and it is the pattern every template page follows:

---
import { getEmDashCollection } from "emdash";

const { entries: posts } = await getEmDashCollection("posts", {
  orderBy: { published_at: "desc" },
});
---
<ul>
  {posts.map((post) => <li>{post.data.title}</li>)}
</ul>

Back up the encryption key. EmDash uses EMDASH_ENCRYPTION_KEY to encrypt plugin secrets stored in the database, and it cannot read them without the same key. Do not commit .env, and save the key in a password manager before you deploy.

Step 5: Put it online

On a Node.js server

npm run build
node ./dist/server/entry.mjs

The server listens on port 4321 by default. Three things matter in production:

  • The built server does not load .env automatically. Set EMDASH_ENCRYPTION_KEY in your host's environment settings. For a local test, run node --env-file=.env ./dist/server/entry.mjs.
  • Behind a reverse proxy that handles HTTPS, set EMDASH_SITE_URL=https://example.com for both the build and the running server, so links and sign-in use the public address.
  • Keep the process running. Scheduled publishing only happens while a Node.js process is up.

Hosting companies planning to offer this will find the server requirements in our guide to EmDash for web hosts.

On Cloudflare Workers

Scaffold with the Cloudflare Workers target, then:

npx wrangler login
npm run build
npx wrangler deploy
npx wrangler secret put EMDASH_ENCRYPTION_KEY

When wrangler secret put asks for a value, paste the key from your .env file. On the first deploy, Wrangler creates the D1 database and the R2 bucket named in wrangler.jsonc. Later deploys reconnect to the same ones, so do not rename them. The template also includes a Cron Trigger, which is what publishes scheduled posts on Cloudflare.

Whichever host you choose, expect to register a new passkey on the live site. Passkeys are bound to a domain, so the one you created for localhost:4321 will not sign you in at your real address. A new deployment normally starts with its own empty database, so you run the setup wizard again on the live domain and register a passkey there.

Adding EmDash to an existing Astro site

You do not have to start from a template. On a project running Astro 6 or later, install the packages and register them in astro.config.mjs:

npm install emdash @astrojs/node @astrojs/react react react-dom
npx emdash secrets generate --write .env

This switches the site to server output, which changes how it is built and hosted, so commit your work first. The official existing project guide has the full config.

Common first-install problems

  • The install step fails. The project files stay in place. Run the retry command the scaffolder prints.
  • A SQLite "ExperimentalWarning" in the terminal. Node.js 22 prints this for its built-in SQLite driver. It is harmless, and Node.js 24 does not show it.
  • Search returns a 503 error on your server. EmDash search needs SQLite's FTS5 extension, which depends on how your Node.js binary was compiled. Switch to a Node.js build that includes it.
  • "Passkey authentication failed". Usually the passkey was created for a different domain. Register one for the address you are on.

Where to go next

From here, the official getting started guide links on to content modeling and querying, and the deployment guides for Node.js and Cloudflare cover production settings in depth. Moving an existing site? Our WordPress to EmDash migration guide covers the importer. Before installing plugins, read how the plugin sandbox works. And if you would rather have it built and looked after for you, that is what our EmDash team does.

Frequently asked questions

Do I need a Cloudflare account to install EmDash?

No. Choose Node.js when the scaffolder asks where you will deploy. The site then uses SQLite and local file storage and runs on any machine or server with Node.js 22.23.4 or later.

Where is the EmDash admin?

At /_emdash/admin/ on your site, for example http://localhost:4321/_emdash/admin/ during development. The first visit to a new site opens the setup wizard.

Can I add EmDash to an Astro site I already have?

Yes, on Astro 6 or later. You install emdash with a server adapter and React, add the integration to your Astro config, and create src/live.config.ts. The site moves to server rendering as part of this.

How do I update EmDash later?

Run npx upgrade-emdash@latest --dry-run in the project to see the plan, then run it without the flag. It updates the EmDash packages and writes a work order to .emdash/UPGRADE.md. It does not change the layouts and components copied from your template.

Em Workers

EmDash and Astro sites at revolutionary pricing.

Lightning-fast, secure websites delivered on EmDash and Astro. For the AI-curious bunch.