emdash-github-actions

---
name: emdash-github-actions
description: |
license: MIT
---

# EmDash Plugin GitHub Actions

This skill helps you set up a comprehensive CI/CD pipeline for EmDash plugins using GitHub Actions. EmDash is a full-stack TypeScript CMS based on Astro, so its plugin ecosystem is entirely TypeScript-based.

## What this skill covers

There are several categories of workflows that a healthy EmDash plugin should have. Not every plugin needs all of them — the right mix depends on the plugin's complexity, whether it has a React admin UI, whether it has tests, etc. Your job is to figure out which ones are relevant and set them up.

The workflows fall into these categories:

1. **Type checking** — TypeScript strict mode with emdash peer dependency
2. **Code quality** — ESLint with TypeScript support
3. **Testing** — Vitest or similar TypeScript-native test runner
4. **Security** — npm audit for dependency vulnerabilities
5. **Deployment** — Automated npm publish on tag/release

Read `references/workflows.md` for the detailed configuration of each workflow, including ready-to-use YAML templates and configuration files.

## How to approach a request

### Step 1: Understand the plugin

Before writing any workflow files, figure out what you're working with:

- **What does the plugin do?** Check the `package.json` description and `src/index.ts` exports. EmDash plugins typically hook into `page:metadata`, `page:fragment`, content hooks, or provide admin UI.
- **Does it have a React admin UI?** Check for `.tsx` files or `admin.tsx`. If yes, the type-check needs `@types/react` and `--jsx react-jsx`.
- **Does it have tests?** Check for a `tests/` or `__tests__/` directory, or a `vitest.config.ts`. If yes, set up the test workflow. If not, mention that adding tests would be valuable but don't force it.
- **What are its peer dependencies?** Check `package.json` for `peerDependencies`. EmDash plugins always depend on `emdash` and may depend on `react`, `astro`, etc.
- **Does it use additional npm dependencies?** Check for `dependencies` in `package.json`. If yes, the CI needs an `npm install` step.
- **Is it published to npm?** Check if the package name is scoped (e.g., `@org/emdash-plugin-foo`) and whether it has a `publishConfig`. If yes, the deploy workflow is relevant.

### Step 2: Recommend a set of workflows

Based on what you found, recommend which workflows to set up. A good default for most plugins:

- TypeScript type-check (almost always — this is the most valuable check)
- ESLint (if the plugin has more than a handful of files)
- npm audit (cheap security check, almost always worth it)

And conditionally:

- Vitest tests (if tests exist)
- npm publish (if the plugin is published to npm)

### Step 3: Create the workflow files

Create each workflow as a separate YAML file in `.github/workflows/`. Using separate files rather than one monolithic workflow gives clearer feedback in PRs (each check shows independently) and makes it easier to enable/disable individual checks.

Use the templates from `references/workflows.md` as starting points, but adapt them to the specific plugin. Common adaptations include:

- Adding `@types/react` if the plugin has `.tsx` files
- Adding additional peer dependencies that provide types
- Adjusting file paths for the type-check and lint commands
- Configuring the npm publish scope and access level

### Step 4: Create supporting config files

Depending on which workflows you set up, you may also need:

- `tsconfig.json` — TypeScript configuration (if not already present)
- `eslint.config.js` — ESLint flat config with TypeScript support
- `vitest.config.ts` — Vitest configuration

### Step 5: Set up secrets reminder

If you're adding the npm publish workflow, remind the user that they need to configure a repository secret in GitHub:

- `NPM_TOKEN` — Their npm access token with publish permissions

Walk them through: Repository Settings > Secrets and variables > Actions > New repository secret.

For scoped packages (`@org/package-name`), the token must have access to the organization.

## Naming conventions

Use descriptive workflow file names that make it obvious what each one does:

- `ci.yml` — TypeScript type-checking (the primary CI check)
- `lint.yml` — ESLint
- `test.yml` — Vitest/test runner
- `security.yml` — npm audit
- `publish.yml` — npm publish on release

## Important details

**Node.js version**: Use Node.js 22 as the default. EmDash is built on modern TypeScript and Astro, so there's no need to support older Node versions. Use `actions/checkout@v5` and `actions/setup-node@v5` (v5 runs on Node.js 24 runners, avoiding the Node.js 20 deprecation).

**Peer dependency installation**: EmDash plugins declare `emdash` as a peer dependency. For type-checking in CI, you must explicitly install `emdash` (and `@types/react` if the plugin has `.tsx` files) since peer dependencies aren't auto-installed in a standalone plugin repo.

**The `--skipLibCheck` flag**: Use `--skipLibCheck` when running `tsc` in CI. EmDash and its transitive dependencies may have internal type issues that aren't relevant to the plugin author. `--skipLibCheck` skips checking `.d.ts` files while still fully checking the plugin's own source code.

**The `find` command for file discovery**: Don't use shell globs like `src/**/*.ts` in CI commands — they fail when no files match at a given depth. Use `$(find src -name '*.ts' -o -name '*.tsx')` instead.

**Branch naming**: Most EmDash plugin repos use `main` as the default branch. Always check the actual repo and use the correct branch name in workflow triggers.