Installing plugins

Two paths

Every PlugDash plugin is installed in two places: once in code (npm + a single line in astro.config.mjs) and optionally in the EmDash admin (where you configure options like collections or thresholds). The code path is required. The admin path is for adjusting configuration after install - never for first install.

The code path (required)

The worked example below uses @plugdash/readtime. Every plugin follows this exact shape.

Step 1: npm install

Step 2: register in astro.config.mjs

Open astro.config.mjs at the root of your Astro project. Import the plugin at the top of the file, then add it to the plugins array of the emdash() integration - the one that sits inside Astro's top-level integrations array. The full file looks like this:

// astro.config.mjs
import { defineConfig } from "astro/config"
import emdash from "emdash/astro"
import { readtimePlugin } from "@plugdash/readtime"

export default defineConfig({
  integrations: [
    emdash({
      plugins: [
        readtimePlugin({ collections: ["blog"] }),
      ],
    }),
  ],
})

Two things to keep straight: emdash() is an Astro integration, so it goes in Astro's integrations array. Each plugdash plugin goes inside emdash()'s own plugins array - not alongside emdash() itself.

The plugin's options object (here, { collections: ["blog"] }) seeds defaults into the plugin's KV store the first time it runs. After that, the admin becomes the source of truth for configuration - edits there persist across restarts.

Step 3: restart the dev server

EmDash runs plugin registration once at startup. Any change to the plugins array needs a server restart to pick up. pnpm dev again and you're done.

The admin path (configure)

After the code install, you can change plugin settings without touching the config file. Plugins that expose configuration render their own admin page automatically.

Open the admin

Go to /_emdash/admin on your running site. Log in.

Find the plugin page

In the admin sidebar, look for the Plugins section. Each installed plugin that declares an admin page shows up as its own entry (e.g. "readtime", "sharepost"). Click one to open its settings.

If a plugin has no configurable options (like @plugdash/callout), it will not appear here. It is still installed - it just has nothing to configure.

Change settings

Typical settings you can adjust in the admin:

• readtime: words per minute (default 238), which collections to process
• sharepost: via handle, which platforms to generate URLs for
• tocgen: minimum heading count to include a TOC, max depth
• shortlink: autoCreate on publish, code length
• autobuild: hook URL, debounce window, collections, statuses
• heartpost: no admin settings - stateless
• callout: no admin settings - just registers the block type

Settings saved in the admin take effect on the next publish. No restart needed.

Add the component to your theme

After install, add the companion Astro component to the relevant layout - usually src/layouts/Post.astro for blog posts:

---
import ReadingTime from "@plugdash/readtime/ReadingTime.astro"
---
<ReadingTime post={post} />

Remove a plugin

1. Remove the plugin from the plugins array in astro.config.mjs
2. Remove any companion component imports from your layouts
3. Run npm uninstall @plugdash/[name]
4. Restart the dev server

The plugin's KV namespace and any metadata it wrote to posts stays on disk. Delete it manually from the admin if you want a clean slate.

Troubleshooting

• Plugin doesn't appear in admin: it likely has no configurable options. Only plugins that declare an admin page show up.
• Metadata not appearing on posts: publish the post again. Most plugins run on content:afterSave - existing posts won't get new metadata until their next save.
• Component renders nothing: either the metadata isn't populated yet (republish) or the component's required field is missing (e.g. HeartButton needs post.id at the top level).
• Changes not picked up: restart the dev server. Plugin registration is read-once at startup.