EmDash

https://docs.emdashcms.com
Admin
EmDash is an Astro-native content management system that provides type-safe content management, live...
Tokens:414,369
Snippets:3,023
Trust Score:7.1
Update:2 days ago
Show doc for...
Tokens:
Raw
### Install dependencies and start dev server

Source: https://docs.emdashcms.com/themes/overview

Commands to install dependencies and start the generated site after scaffolding.

```bash
cd my-site
npm install
npm run dev
```

--------------------------------

### Clone, install, and build the workspace

Source: https://docs.emdashcms.com/contributing

Initial setup commands to clone the repository, install dependencies with pnpm, and build the workspace.

```bash
git clone https://github.com/emdash-cms/emdash.git
cd emdash
pnpm install
pnpm build
```

--------------------------------

### Start local dev server with pnpm dev

Source: https://docs.emdashcms.com/guides/create-a-blog

Starts the local development server for the scaffolded blog. Open the printed local URL and then /_emdash/admin to complete the setup screen on first run.

```bash
cd my-blog
pnpm dev
```

--------------------------------

### Build and preview with EMDASH_SITE_URL

Source: https://docs.emdashcms.com/deployment/cloudflare

Build the project and start a preview with a custom name and the preview URL passed as EMDASH_SITE_URL. Without siteUrl or EMDASH_SITE_URL, setup fails with SITE_URL_REQUIRED. Use the same preview name in --name and in the URL.

```bash
pnpm build
pnpm wrangler preview --name my-branch \
  --var EMDASH_SITE_URL:https://my-branch-my-emdash-site.example.workers.dev
```

--------------------------------

### plugin:install

Source: https://docs.emdashcms.com/reference/hooks

Runs when a plugin is first installed. Use for initial setup, creating storage collections, or seeding data. Receives an empty event object and has no return value.

```APIDOC
## plugin:install

### Description
Runs when a plugin is first installed. Use for initial setup, creating storage collections, or seeding data.

### Method
Hook

### Event
Empty object

### Context
- `ctx.settings.set(key, value)` - Sets a setting
- `ctx.log.info(message)` - Logs an info message

### Return Value
None

### Example
```javascript
hooks: {
  "plugin:install": async (event, ctx) => {
    // Initialize default settings
    await ctx.settings.set("enabled", true);
    await ctx.settings.set("threshold", 100);

    ctx.log.info("Plugin installed successfully");
  },
}
```
```

--------------------------------

### Start the development server with npm run dev

Source: https://docs.emdashcms.com/existing-project

Run this command in the project root to start the Astro development server. After starting, open http://localhost:4321/_emdash/admin/ to access the setup wizard.

```bash
npm run dev
```

--------------------------------

### Install @emdash-cms/plugin-test and vitest

Source: https://docs.emdashcms.com/plugins/creating-plugins/testing

Install the test host and Vitest as development dependencies for an existing plugin project. Projects created by `emdash-plugin init` already include this setup.

```bash
pnpm add -D @emdash-cms/plugin-test vitest
```

--------------------------------

### Install skills with npx skills add

Source: https://docs.emdashcms.com/agent-skills

Run in your project to install skills. It asks which skills and assistants to install for. Add `--skill <name>` to choose skills up front, or `-g` to install for your user account instead of the current project.

```bash
npx skills add emdash-cms/skills
```

--------------------------------

### plugin:install hook

Source: https://docs.emdashcms.com/reference/hooks

Runs when a plugin is first installed. Use for initial setup, creating storage collections, or seeding data. Receives an empty event object and has no return value.

```javascript
hooks: {
  "plugin:install": async (event, ctx) => {
    // Initialize default settings
    await ctx.settings.set("enabled", true);
    await ctx.settings.set("threshold", 100);


    ctx.log.info("Plugin installed successfully");
  },
}
```

--------------------------------

### Scaffold EmDash site with npm, pnpm, yarn, or bun

Source: https://docs.emdashcms.com/getting-started

Start the interactive scaffolder for EmDash. Choose the following options when prompted: Project name: my-emdash-site, Where will you deploy? Node.js, Which template? Starter, Which package manager? Keep the package manager detected from the command, Install dependencies? Yes. These choices create a general-purpose Node.js site with Posts and Pages. The scaffolder also writes a generated EMDASH_ENCRYPTION_KEY to the gitignored .env file. If dependency installation fails, the project files remain in place; run the retry command printed by the scaffolder before continuing.

```bash
npm create emdash@latest
```

```bash
pnpm create emdash@latest
```

```bash
yarn create emdash
```

```bash
bun create emdash@latest
```

--------------------------------

### Install with yarn

Source: https://docs.emdashcms.com/guides/x402-payments

Install the @emdash-cms/x402 package using yarn.

```bash
yarn add @emdash-cms/x402
```

--------------------------------

### Install dependencies with pnpm install

Source: https://docs.emdashcms.com/plugins/creating-plugins/your-first-plugin

Installs the generated package's dependencies after scaffolding. Run from the save-log directory.

```bash
cd save-log
pnpm install
```

--------------------------------

### Install with pnpm

Source: https://docs.emdashcms.com/guides/x402-payments

Install the @emdash-cms/x402 package using pnpm.

```bash
pnpm add @emdash-cms/x402
```

--------------------------------

### Install with npm

Source: https://docs.emdashcms.com/guides/x402-payments

Install the @emdash-cms/x402 package using npm.

```bash
npm install @emdash-cms/x402
```

--------------------------------

### Add EmDash marketplace and install plugin with Codex CLI

Source: https://docs.emdashcms.com/agent-skills

Add the EmDash marketplace and install its plugin with the Codex CLI. The plugin includes all EmDash skills. Start a new Codex task after installing it.

```bash
codex plugin marketplace add emdash-cms/skills
codex plugin add emdash@emdash
```

--------------------------------

### Add EmDash marketplace and install plugin with Claude Code

Source: https://docs.emdashcms.com/agent-skills

Add the repository as a plugin marketplace, then install the `emdash` plugin. Claude Code names the installed skills with an `emdash:` prefix, for example `emdash:building-emdash-site`.

```bash
/plugin marketplace add emdash-cms/skills
/plugin install emdash@emdash
```

--------------------------------

### Start the site locally

Source: https://docs.emdashcms.com/deployment/updating

Start the dev server to generate emdash-env.d.ts and run pending core migrations on the first request.

```bash
pnpm dev
```

--------------------------------

### Install the CLI with pnpm add -D

Source: https://docs.emdashcms.com/plugins/creating-plugins/cli

Adds the CLI as a development dependency to an existing plugin. The examples use `pnpm exec emdash-plugin` so each command runs the installed version.

```bash
pnpm add -D @emdash-cms/plugin-cli
```

--------------------------------

### Start the primary development demo

Source: https://docs.emdashcms.com/contributing

Starts the demo from the demos/simple directory. The demo runs on Node.js with SQLite at http://localhost:4321 and applies the schema from seed/seed.json on first request.

```bash
cd demos/simple
pnpm dev
```

--------------------------------

### Compile and run the demo

Source: https://docs.emdashcms.com/contributing/translating

Commands to compile locale files, build the project, and start the demo development server. Run these to test your translations in the demo.

```bash
pnpm run locale:compile
pnpm build
pnpm --filter emdash-demo dev

```

--------------------------------

### Build the site

Source: https://docs.emdashcms.com/deployment/updating

Build the site to write the migration manifest for the installed version.

```bash
pnpm build
```

--------------------------------

### Run release setup command

Source: https://docs.emdashcms.com/plugins/creating-plugins/cli

Run from a plugin directory or pass --dir <plugin-directory> to prepare the package profile and create a shared .github/workflows/emdash-release.yml at the repository root. Accepts profile setup flags plus workflow options like --service-url, --action-ref, --trigger, and --force.

```bash
emdash-plugin release setup
```

--------------------------------

### Check Node.js and Astro versions

Source: https://docs.emdashcms.com/existing-project

Verify Node.js 22.16+ and Astro 6+ are installed before starting the integration.

```bash
node --version
npx astro --version
```

--------------------------------

### s3(config?) - S3-compatible storage examples

Source: https://docs.emdashcms.com/reference/configuration

Shows three ways to configure S3 storage: all fields from environment variables, a mix of config and environment, and all explicit values. Missing required fields cause startup failure with MISSING_S3_CONFIG.

```javascript
// All fields from S3_* environment variables (Node container deployments)
s3()
```

```javascript
// Mix: CDN from config, rest from environment
s3({ publicUrl: "https://cdn.example.com" })
```

```javascript
// All explicit
s3({
  endpoint: "https://xxx.r2.cloudflarestorage.com",
  bucket: "media",
  accessKeyId: process.env.R2_ACCESS_KEY_ID,
  secretAccessKey: process.env.R2_SECRET_ACCESS_KEY,
  publicUrl: "https://cdn.example.com",
})
```

--------------------------------

### Query-string input for GET/HEAD/DELETE

Source: https://docs.emdashcms.com/plugins/creating-plugins/api-routes

Example of parsing query-string input for a GET route, including repeated keys and type coercion.

```APIDOC
## Query-string input for GET/HEAD/DELETE

### Description
Shows how to parse query-string input for bodyless methods, with repeated keys becoming arrays and type coercion for numbers.

### Method
GET

### Endpoint
/_emdash/api/plugins/<slug>/list?status=open&limit=20&tag=a&tag=b

### Parameters
#### Query Parameters
- **status** (enum) - Optional - Filter by status (open or closed).
- **limit** (number) - Optional - Maximum number of items (1-100). Defaults to 20.
- **tag** (string or string[]) - Optional - Tag filter; repeated keys become an array.

### Request Example
```
const listInput = z.object({
  status: z.enum(["open", "closed"]).optional(),
  limit: z.coerce.number().int().min(1).max(100).default(20),
  tag: z.union([z.string(), z.array(z.string())]).optional(),
});

routes: {
  list: {
    // GET /_emdash/api/plugins/<slug>/list?status=open&limit=20&tag=a&tag=b
    handler: async (routeCtx, ctx) => {
      const parsed = listInput.safeParse(routeCtx.input);
      if (!parsed.success) return { ok: false, error: "INVALID_QUERY" };
      const { status, limit, tag } = parsed.data;
      // ...
    },
  },
},
```

### Response
#### Success Response (200)
- **ok** (boolean) - True if the query was valid.

#### Error Response (400)
- **ok** (boolean) - False.
- **error** (string) - INVALID_QUERY.

#### Response Example
```json
{
  "ok": true
}
```
```

--------------------------------

### Initialize a plugin with @emdash-cms/plugin-cli init

Source: https://docs.emdashcms.com/plugins/creating-plugins/cli

Scaffolds a new plugin project with the default interactive setup. Creates emdash-plugin.jsonc, src/plugin.ts, package.json, tsconfig.json, vitest.config.ts, a workerd-backed test, README, AGENTS.md, a local creating-plugins skill, and package-manager configuration. The CLI detects the launching package manager (npm, pnpm, Yarn, or Bun) and generates matching commands; override with --package-manager.

```bash
pnpm dlx @emdash-cms/plugin-cli init my-plugin

```

--------------------------------

### SQLite file path examples

Source: https://docs.emdashcms.com/deployment/database

Shows three ways to specify the SQLite database file path: relative, absolute, and from an environment variable. All must start with `file:`.

```javascript
// Relative path
database: sqlite({ url: "file:./data/emdash.db" });


// Absolute path
database: sqlite({ url: "file:/var/data/emdash.db" });


// From environment variable
database: sqlite({ url: `file:${process.env.DATABASE_PATH}` });
```

--------------------------------

### KV and Settings Operations

Source: https://docs.emdashcms.com/plugins/creating-plugins/settings

Examples of performing basic read/write operations using ctx.settings and ctx.kv.

```javascript
const enabled = await ctx.settings.get<boolean>("enabled");
await ctx.kv.set("state:lastSync", new Date().toISOString());
const deleted = await ctx.kv.delete("cache:feed");
const allSettings = await ctx.settings.list();
```

--------------------------------

### Locale URL prefix example

Source: https://docs.emdashcms.com/guides/internationalization

Shows the default routing behavior where the default locale (en) is unprefixed and other locales (fr) get a prefix. This is the Astro default 'prefix-other-locales' strategy.

```text
# prefix-other-locales (Astro default)
/blog/my-post          → en (default locale, no prefix)
/fr/blog/mon-article   → fr
```

--------------------------------

### Start EmDash development server with npm, pnpm, yarn, or bun

Source: https://docs.emdashcms.com/getting-started

Enter the project directory and start the development server. Keep this terminal open. Astro prints the local site URL, normally http://localhost:4321/. Do not commit .env; back up EMDASH_ENCRYPTION_KEY before deploying the site.

```bash
cd my-emdash-site
npm run dev
```

```bash
cd my-emdash-site
pnpm dev
```

```bash
cd my-emdash-site
yarn dev
```

```bash
cd my-emdash-site
bun dev
```

--------------------------------

### Use taxonomy functions to get terms and entries

Source: https://docs.emdashcms.com/reference/api

Example usage of getTaxonomyTerms, getTerm, getEntryTerms, and getEntriesByTerm. Demonstrates fetching all terms, a single term, terms for an entry, and entries with a specific term.

```typescript
import { getTaxonomyTerms, getTerm, getEntryTerms, getEntriesByTerm } from "emdash";


// Get all terms for a taxonomy (tree structure for hierarchical)
const categories = await getTaxonomyTerms("category");


// Get single term
const news = await getTerm("category", "news");


// Get terms assigned to a content entry
const postCategories = await getEntryTerms("posts", "post-123", "category");


// Get entries with a specific term
const newsPosts = await getEntriesByTerm("posts", "category", "news");
```

--------------------------------

### Configure Cloudflare sandbox runner in astro.config.mjs

Source: https://docs.emdashcms.com/plugins/registry

Adds the Cloudflare sandbox runner to the emdash() configuration in astro.config.mjs to enable registry installs. Requires platform-specific plugin sandbox setup and configured storage.

```javascript
import { defineConfig } from "astro/config";
import { sandbox } from "@emdash-cms/cloudflare";
import emdash from "emdash/astro";


export default defineConfig({
  integrations: [
    emdash({
      sandboxRunner: sandbox(),
    }),
  ],
});
```

--------------------------------

### Build the project with npm run build

Source: https://docs.emdashcms.com/deployment/nodejs

Builds the project for production. Run this before starting the server.

```bash
npm run build
```

--------------------------------

### Admin manifest JSON structure

Source: https://docs.emdashcms.com/contributing/architecture

Abridged example of the manifest returned by GET /_emdash/api/manifest, describing collections, fields, plugins, taxonomies, and version. The admin uses this to build navigation and field editors without rebuilding.

```json
{
  "collections": {
    "posts": {
      "label": "Blog Posts",
      "labelSingular": "Post",
      "supports": ["drafts", "revisions", "preview"],
      "fields": {
        "title": { "kind": "string", "label": "Title", "required": true }
      }
    }
  },
  "plugins": {
    "audit-log": { "version": "0.2.1", "enabled": true }
  },
  "taxonomies": [
    { "name": "category", "label": "Categories", "hierarchical": true }
  ],
  "version": "0.37.0"
}

```

--------------------------------

### Migrate, deploy, and check

Source: https://docs.emdashcms.com/deployment/core-migrations

After confirming the target, start the interactive migration, deploy the same build, and check the deployed schema. Review the target again at the prompt before confirming.

```bash
pnpm emdash migrate
pnpm wrangler deploy
pnpm emdash migrate --check

```

--------------------------------

### Start a release with package tags

Source: https://docs.emdashcms.com/plugins/creating-plugins/delegated-releases

Creates a version tag and pushes it to start a release. The workflow runs for package tags matching <slug>@<version>.

```bash
git tag gallery@1.2.3
git push origin gallery@1.2.3
```

--------------------------------

### Register the plugin in astro.config.mjs

Source: https://docs.emdashcms.com/plugins/creating-plugins/your-first-plugin

Import the generated default export from the plugin and add it to the sandboxed array. This example uses the Node.js workerd runner; keep the runner already configured by your site if it uses Cloudflare Workers or another supported setup.

```javascript
import { defineConfig } from "astro/config";
import emdash from "emdash/astro";
import saveLog from "save-log";


export default defineConfig({
  integrations: [
    emdash({
      sandboxed: [saveLog],
      sandboxRunner: "@emdash-cms/sandbox-workerd/sandbox",
    }),
  ],
});
```

--------------------------------

### Run emdash-plugin profile setup

Source: https://docs.emdashcms.com/plugins/creating-plugins/cli

Run the interactive profile setup from the plugin directory. Use --dir to specify the plugin directory when running from elsewhere in a monorepo.

```bash
emdash-plugin profile setup

```

--------------------------------

### Restrict HTTP methods with `methods` array

Source: https://docs.emdashcms.com/plugins/creating-plugins/api-routes

Declare `methods` on a route to restrict which HTTP methods can invoke it. EmDash returns `405 Method Not Allowed` with an `Allow` header before calling the handler when the request method is not declared. The example shows a route with `GET` and `DELETE` methods and a handler that parses input and performs storage operations.

```javascript
routes: {
  item: {
    methods: ["GET", "DELETE"],
    handler: async (routeCtx, ctx) => {
      const parsed = z.object({ id: z.string() }).safeParse(routeCtx.input);
      if (!parsed.success) return { ok: false, error: "INVALID_ID" };
      const { id } = parsed.data;


      switch (routeCtx.request.method) {
        case "GET":
          return await ctx.storage.items.get(id);
        case "DELETE":
          await ctx.storage.items.delete(id);
          return { deleted: true };
      }
    },
  },
},

```

--------------------------------

### Build and deploy preview environment

Source: https://docs.emdashcms.com/deployment/cloudflare

Commands to build the project and deploy the preview environment. The first request applies pending core migrations through the default auto mode.

```bash
pnpm build
pnpm wrangler deploy --env preview

```

--------------------------------

### Start the Node.js server

Source: https://docs.emdashcms.com/deployment/nodejs

Starts the server from the built output. The standalone Node entry does not load .env automatically; set EMDASH_ENCRYPTION_KEY and other credentials in the environment. For local runs using the generated .env file, use node --env-file=.env.

```bash
node ./dist/server/entry.mjs
```

--------------------------------

### Seed settings object with version and common properties

Source: https://docs.emdashcms.com/themes/seed-files

Example of a partial site-settings object in a seed file. Common properties include title, tagline, logo, favicon, url, postsPerPage, dateFormat, timezone, social, and seo. The setup wizard replaces seeded title and tagline; default onConflict: "skip" preserves those values on reapplication.

```json
{
  "version": "1",
  "settings": {
    "title": "Field Notes",
    "tagline": "Reports from the team",
    "postsPerPage": 12,
    "dateFormat": "MMMM d, yyyy",
    "timezone": "Europe/London"
  }
}
```

--------------------------------

### Install the local plugin package with pnpm

Source: https://docs.emdashcms.com/plugins/creating-plugins/your-first-plugin

Run this command from the site's directory to install the local plugin package. Adjust the relative path if the projects are not siblings.

```bash
pnpm add file:../save-log
```

--------------------------------

### GET /_emdash/api/admin/transfer/capabilities

Source: https://docs.emdashcms.com/reference/rest-api

Gets site transfer capabilities.

```APIDOC
## GET /_emdash/api/admin/transfer/capabilities

### Description
Gets site transfer capabilities.

### Method
GET

### Endpoint
/_emdash/api/admin/transfer/capabilities

### Response
#### Success Response (200)
Returns transfer capabilities.

#### Response Example
{
  "capabilities": {}
}
```

--------------------------------

### Install EmDash, Node.js adapter, and React support

Source: https://docs.emdashcms.com/existing-project

Install EmDash, the Node.js adapter, and React support using npm, pnpm, or yarn. EmDash uses React for the admin panel even if the public site has no React components.

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

```pnpm
pnpm add emdash @astrojs/node @astrojs/react react react-dom
```

```yarn
yarn add emdash @astrojs/node @astrojs/react react react-dom
```
Tokens:
Raw