Install EmDash and Set Up Your Website

Chapters

Updated 16 October 2026.

Install EmDash with npm create emdash@latest, start the development server, and complete setup at /_emdash/admin/. You can run your website on Node.js with SQLite and local uploads, or Cloudflare Workers with D1 and R2.

The video walkthrough was tested on EmDash 1.1.0 on 2 October 2026, using Astro 7.3.5 and the Node.js Blog template. Its admin screens show that version. EmDash 1.3.0 was published on 15 October 2026.

Install EmDash: quick start

You need Node.js 22.16 or later, npm or another supported package manager, a terminal, and a browser that supports passkeys. You can work locally without a cloud account. Check Node.js first:

node --version

Start the installer with one of these commands. The official getting-started instructions support npm, pnpm, yarn and bun:

# npm
npm create emdash@latest

# pnpm
pnpm create emdash@latest

# yarn
yarn create emdash

# bun
bun create emdash@latest

Choose your project name, deployment platform, template and package manager, then allow dependency installation. For the video’s blog, choose Node.js and Blog. With npm and a project named my-site, start it with:

cd my-site
npm run dev

Open http://localhost:4321/_emdash/admin/. Enter your site details, choose whether to include sample content, enter your email and name, and register a passkey. Keep the terminal running.

The video was recorded on Node.js 25, where npm install printed an EBADENGINE warning because one EmDash package asks for ^22.22.2 || ^24.15.0 || >=26.0.0. The site still built and ran in that test. Node.js 24.15 or later in the 24 release line satisfies that package’s requirement.

Create the project

The project folder holds your site’s files. Follow the installer prompts:

  1. Enter a project name, such as my-site.
  2. Choose Node.js for the walkthrough. It uses a SQLite file for content and a local folder for uploads. Cloudflare Workers uses D1 for the database and R2 for storage. Your choice sets the adapters in astro.config.mjs.
  3. Choose Blog, which includes a design and sample posts. The other choices are Starter, Marketing and Portfolio.
  4. Choose your package manager and let the installer install dependencies.

If dependency installation fails, the project files remain in place. Run the retry command printed by the installer.

The installer writes EMDASH_ENCRYPTION_KEY to .env and adds .env to .gitignore. EmDash uses this key to encrypt plugin secrets. Keep the file private and back up the key separately: a database backup does not contain it, and losing it makes those secrets unreadable.

To generate a key for a project that needs one, run:

npx emdash secrets generate

Keep an existing site’s key when moving or deploying it. Generating a replacement does not recover secrets encrypted with the previous key.

Run it and sign in

Once installation finishes, enter your project folder and start the development server:

cd my-site
npm run dev

If you already started it during the quick start, leave that server running. With another package manager, use pnpm dev, yarn dev or bun dev. Astro prints the local address, normally http://localhost:4321/.

Follow the site’s admin link or open http://localhost:4321/_emdash/admin/:

  1. Enter your site title and optional tagline.
  2. Keep the sample content, or choose an empty site.
  3. Enter your email and optional name.
  4. Create a passkey, then select Open the dashboard.

A passkey is a login saved on your device that you use with your fingerprint or device password. It belongs to the address where you created it. Your localhost passkey will not work on your live domain, so you need a new one there.

The terminal also prints a Dev bypass link at /_emdash/api/setup/dev-bypass?redirect=/_emdash/admin. It signs you in as a dev admin without a passkey and returns 403 outside development. The video follows the setup wizard.

A tour of the admin

  • Dashboard shows a content summary and your latest changes.
  • Calendar shows published and scheduled posts by month.
  • Pages holds pages that rarely change, such as About.
  • Posts lists blog posts with their status and date.
  • Media holds uploaded images and files.
  • Comments lets you approve, reject or delete visitors’ comments.
  • Menus controls navigation links.
  • Redirects sends old addresses to new ones and lists pages that were not found.
  • Widgets provides sidebar and footer blocks, including search.
  • Sections holds reusable content, such as an author bio.
  • Categories groups posts into broad topics.
  • Tags adds smaller labels, with multiple tags per post.
  • Bylines holds author names, including guest writers.
  • Content Types defines content collections and their fields.
  • Byline Schema adds author fields, such as a job title.
  • Users lets you invite people and set their permissions.
  • Plugins lists installed add-ons.
  • Registry is the public plugin catalog.
  • Import brings in WordPress posts and pages.
  • Settings holds site identity, search engine options and security.

Settings

In the tested install, the wizard’s title and tagline did not replace the template’s values. The seed had been applied before the wizard, and the site still said My Blog. EmDash 1.2 fixed this for new sites; upgrading an existing site keeps its stored values.

  1. Open Settings → General.
  2. Check your title and tagline and change them if necessary. The video uses Long Walks.
  3. Save your changes.

General settings also holds your logo, favicon and Site URL. The favicon appears in the browser tab. Site URL is used for canonical links and sitemaps. Since 1.2, it also supplies the origin for sign-in, invitation, recovery and comment notification emails when no site URL is configured in code or the environment. Check it when moving domains.

EmDash 1.3 adds Disallow AI training under Settings → SEO. It is off by default. Turning it on adds training-crawler rules and Content-Signal: search=yes, ai-train=no to robots.txt, including a custom robots file. Search engine access follows your other rules. See the 1.3 release notes.

Write and publish a post

  1. Open Posts and select Add New. Existing posts can be filtered by status, author and date.
  2. Type a title and paragraph. Type / for blocks including headings, lists, quotes, code, tables, images and galleries. The toolbar includes bold, italics, links, lists and quotes.
  3. Under Featured Image, select browse, then Upload files. Upload a photo and choose it.
  4. Check the slug on the right. It forms the end of the post’s address and is filled in from the title.
  5. Select Save. The draft is not visible on the site.
  6. Select Publish now and confirm.
  7. Open the published post and check its title, image and text.

Later edits are saved as draft changes. Visitors keep seeing the published version until you select Publish changes. You can also Discard changes. Restoring an earlier version from Revisions creates a draft to review and publish.

In EmDash 1.3’s revision history, selecting a version shows it read-only in the editor. Added text is highlighted, removed text is struck through, and changes have readable descriptions. Save and Publish pause while a version is open; Restore appears at the bottom.

Schedule publishes later. On Node.js, the server process must be running at the scheduled time. For posts that should expire, our Auto Unpublish Posts plugin can unpublish, trash or retag them on a date. The free plugin includes collection defaults and email alerts; Pro adds rules, bulk scheduling and CSV.

Media

Your featured image now appears in Media. Select it, add alt text describing the picture for people using screen readers, and save.

The Node.js template stores uploads in ./uploads and content in ./data.db, both inside the project folder. Cloudflare stores uploads in R2 and content in D1.

Menus

  1. Open Menus → Primary Navigation.
  2. Select Add Custom Link.
  3. Enter a label and your published post’s address.
  4. Reload the site to check the header link.

The Blog template’s header reads this menu on the next page load. You can also use Add Content.

EmDash 1.3 adds menu renaming and CSS classes. The pencil beside the menu title renames the locale version being edited. A CSS classes field is available when adding a custom link or editing an item.

Redirects

A redirect helps when you rename a page or want a short link. The video uses /trail as a shortcut to the published post:

  1. Open Redirects and select New Redirect.
  2. Enter /trail as the old address.
  3. Enter the post’s address as the destination and create the redirect.
  4. Visit http://localhost:4321/trail to check it.

Install Comment Spam Protection

Comment Spam Protection checks comments against your rules and explains why each was approved, held for review or marked as spam. Checks run on your site without an outside service, account or API key. The blocked phrase rule below is free; paid upgrades are available through Comment Spam Protection Pro.

Turn on the plugin sandbox

Registry plugins need a sandbox runner, which limits what they can access. Configure it once per site, including on a live Node.js server. You do not repeat this configuration for each plugin.

On Node.js, stop the development server with Control+C and install:

npm install @emdash-cms/sandbox-workerd workerd

Inside the existing emdash({ ... }) options in astro.config.mjs, add sandboxRunner: "@emdash-cms/sandbox-workerd/sandbox", and save. Restart:

npm run dev

Install these packages on the server’s platform with optional dependencies enabled, so the correct workerd binary is included.

With the Cloudflare template, enable "worker_loaders": [{ "binding": "LOADER" }] in wrangler.jsonc. Worker Loader requires the Workers Paid plan. Templates leave the binding commented out unless sandboxed plugins are enabled during scaffolding, allowing deployment on the free plan.

The Cloudflare template includes the runner and Worker entry point. Keep its sandboxRunner: sandbox() configuration and PluginBridge export. Follow the official sandbox instructions when configuring an existing project.

Install and test the plugin

  1. Open Registry, search for Comment Spam Protection, and open it.
  2. Review the permissions, including comment moderation, then select Accept and Install.
  3. Open Comment rules and select the Content tab.
  4. Add crypto giveaway as a blocked phrase. Leave Mark as spam selected and save.
  5. Open Try a comment and test text containing that phrase. This does not post a comment.
  6. Check the result. The video’s test is marked as spam with a reason.

If comments are disabled, open the collection under Content Types and turn on Enable comments.

Put the site online

Node.js production

Before the first visit to a new production site, set its public address. Add siteUrl: "https://yoursite.com" inside the existing EmDash integration, or set the environment variable:

export EMDASH_SITE_URL=https://yoursite.com

Replace the example domain with yours. Set the variable in both the build and server environments. Without a configured public address, Node.js production setup returns SITE_URL_REQUIRED, even on localhost. Local astro dev and production Cloudflare Workers can run setup without this value.

Build and start the server:

npm run build
node --env-file=.env ./dist/server/entry.mjs

The built server does not load .env automatically. The walkthrough template’s npm start script omits --env-file. Pass the file explicitly or supply EMDASH_ENCRYPTION_KEY through your host’s runtime environment.

SQLite and local uploads need persistent disk storage. Back up both and the encryption key. Include the sandbox packages and configuration if you use registry plugins. Keep the server running continuously for scheduled publishing.

Open https://yoursite.com/_emdash/admin/ and complete setup for the new live site, creating a passkey for its domain. The Node.js deployment documentation includes public URL and runtime configuration.

Cloudflare notes

Choose Cloudflare Workers during scaffolding, or use --template cloudflare:blog. The template binds D1 as DB, R2 as MEDIA, and includes a cron trigger for scheduled publishing.

Before the first deploy, change name, database_name and bucket_name in wrangler.jsonc. The template names include my-emdash-site and my-emdash-media. Wrangler creates resources by name on first deployment and reuses names already present in your account. Enable Worker Loader and use the Workers Paid plan for registry plugins.

npx wrangler login
npm run deploy
npx wrangler secret put EMDASH_ENCRYPTION_KEY

The deploy script runs astro build && wrangler deploy. Supply your encryption key when prompted, then open the live admin and complete setup on that domain.

Scheduled publishing requires both the cron trigger and the scheduled handler in the Worker entry point. Cloudflare can take up to 15 minutes to start a new cron trigger. The video’s hosting walkthrough stops before a Cloudflare deployment. Follow the Cloudflare deployment instructions for bindings and scheduled publishing.

Add EmDash to an existing Astro site

An existing project needs Astro 6 or later and Node.js 22.16 or later. Save the project before changing its configuration. For the Node.js integration, install:

npm install emdash @astrojs/node @astrojs/react react react-dom

Register React and EmDash in astro.config.mjs, enable server output, and configure the Node.js adapter, database and media storage. If an adapter is already configured, retain it and follow its deployment requirements instead of adding a second one.

Add the _emdash live collection with emdashLoader() in src/live.config.ts. Existing file-based content collections can remain alongside it. Generate the key:

npx emdash secrets generate --write .env

Exclude .env, the database and uploads from Git. Start the server, complete setup, publish an entry, and connect an Astro page to it. The existing-project instructions include the configuration and a test page. Installing the packages alone does not connect your public pages to EmDash content.

Start with a Peachfin theme

Our Astro themes with EmDash editions ship with plain Markdown content by default and optional EmDash support. Keep Markdown if editing content files suits your site; choose EmDash when you want the browser admin and publishing workflow.

Field Manual has section indexes, numbered libraries and step-by-step articles for guide sites. Common Hours has chapter indexes and numbered steps for blogs. Side Quest uses dated timelines and category shelves, while Open Tabs has panoramic lead stories, recent headlines and dated archives. These layouts suit personal journals, educational publications and business blogs.

Browse all Astro themes for other site types. The Astro Pass includes the Astro theme collection and future Astro themes released while the pass is sold.

Keep EmDash up to date

From your existing project folder, inspect the update and then apply it:

npx upgrade-emdash@latest --dry-run
npx upgrade-emdash@latest

The updater handles direct emdash and @emdash-cms/* dependencies together and writes .emdash/UPGRADE.md. Read that file and complete its actions. It does not update your copied template files, apply database migrations or deploy the site.

Before starting or deploying code with pending migrations or required data changes, create a restorable recovery point. Build the project, then check admin sign-in, public pages, publishing, uploads and any plugins or scheduled tasks. Follow the EmDash updating instructions for migration and deployment requirements.

Frequently asked questions

How do I install EmDash?

Run npm create emdash@latest, choose a project name, deployment platform, template and package manager, then install dependencies. Enter the project folder, run npm run dev, and open http://localhost:4321/_emdash/admin/ to complete setup and register a passkey.

What do I need to install EmDash?

You need Node.js 22.16 or later, npm or another supported package manager, a terminal, and a browser that supports passkeys. A local Node.js site uses SQLite and local media storage, so you can start without a cloud account.

Is EmDash free?

EmDash is free, open-source software under the MIT license. Hosting and paid themes or plugin upgrades have separate costs. Registry plugins on Cloudflare require the Workers Paid plan.

Can I add EmDash to an existing Astro site?

Yes. The official integration requires Astro 6 or later and Node.js 22.16 or later. Add EmDash and React support, configure server rendering and a compatible adapter, connect the live content loader, generate an encryption key, and complete the setup wizard.