Skip to content

UI Library for Design Engineers. Animated components and effects you can copy and paste into your apps. Free. Open Source.

ci: make PR check failures self-explanatory and document CI gates (#994)

Jinho0bd8b9fe0e15
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index af9bf834..ee3e8589 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -18,3 +18,9 @@
| Before | After |
| --- | --- |
| | |
+
+## Checklist
+- [ ] `pnpm check` passes locally
+- [ ] `pnpm build` passes locally
+- [ ] `pnpm build:registry` was run and the generated files are committed (if you changed `registry/` or `config/site.ts` — CI verifies this on every PR)
+- [ ] PR title follows [Conventional Commits](https://www.conventionalcommits.org/) (e.g., `feat(marquee): add reverse prop`)
diff --git a/.github/workflows/code-check.yml b/.github/workflows/code-check.yml
index 372157b0..a40ededb 100644
--- a/.github/workflows/code-check.yml
+++ b/.github/workflows/code-check.yml
@@ -43,7 +43,12 @@ jobs:
- name: Install dependencies
run: pnpm install
- - run: pnpm lint
+ - name: pnpm lint
+ run: |
+ pnpm lint || {
+ echo "::error::Lint errors found. Run 'pnpm lint:fix' locally, fix any remaining errors, then commit."
+ exit 1
+ }
format:
runs-on: ubuntu-latest
@@ -81,7 +86,12 @@ jobs:
- name: Install dependencies
run: pnpm install
- - run: pnpm format:check
+ - name: pnpm format:check
+ run: |
+ pnpm format:check || {
+ echo "::error::Formatting issues found. Run 'pnpm format:fix' locally, then commit."
+ exit 1
+ }
tsc:
runs-on: ubuntu-latest
@@ -153,7 +163,12 @@ jobs:
- name: Install dependencies
run: pnpm install
- - run: pnpm registry-deps:check
+ - name: pnpm registry-deps:check
+ run: |
+ pnpm registry-deps:check || {
+ echo "::error::Registry example dependencies are out of sync. Run 'pnpm registry-deps:fix && pnpm build:registry', then commit registry-examples.ts along with the generated files."
+ exit 1
+ }
build:
runs-on: ubuntu-latest
@@ -224,6 +239,8 @@ jobs:
- name: Install dependencies
run: pnpm install
+ # build:registry must stay regeneration-only: repo-wide lint/format fixes
+ # here could fail on unrelated errors and mask the real drift result.
- name: Build registry artifacts
run: pnpm build:registry
@@ -238,10 +255,8 @@ jobs:
apps/www/public/llms-full.txt)"
if [ -n "$CHANGED_FILES" ]; then
- echo "Registry artifacts are out of date."
+ echo "::error::Registry artifacts are out of date. Run 'pnpm build:registry', then commit the generated files."
echo "Changed files:"
printf '%s\n' "$CHANGED_FILES"
- echo "Run: pnpm build:registry"
- echo "Then commit generated files."
exit 1
fi
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 25fca51e..7143ab87 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -2,7 +2,7 @@
Thank you for your interest in contributing to MagicUI! We appreciate your support and look forward to your contributions. This guide will help you understand the directory structure and provide detailed instructions on how to add a new component to MagicUI.
-Read the [example PR](https://github.com/magicuidesign/magicui/pull/780) to learn which files you need to add. **You only need to change 5 files to add a new component or effect** and it only takes around 10 minutes of work!
+Read the [example PR](https://github.com/magicuidesign/magicui/pull/780) to learn which files you need to add. **You only need to write 5 files to add a new component or effect** (plus committing the registry artifacts that `pnpm build:registry` generates for you) and it only takes around 10 minutes of work!
Once done, open a pull request from your forked repo to the main repo [here](https://github.com/magicuidesign/magicui/compare).
@@ -33,6 +33,8 @@ Once done, open a pull request from your forked repo to the main repo [here](htt
5. **Install dependencies**
+ Requires Node 22 (see `.nvmrc`) and pnpm 9.
+
```bash
pnpm i
```
@@ -239,6 +241,8 @@ Make sure to add any necessary dependencies, tailwind configurations, or other p
pnpm build:registry
```
+This regenerates the registry artifacts (`registry.json`, `registry/__index__.tsx`, `public/registry.json`, `public/r`, `public/llms.txt`, `public/llms-full.txt`). **Commit the generated files together with your component** — CI verifies they are up to date and fails otherwise.
+
## Adding to the showcase
### 1. Create your showcase as a MDX file
@@ -260,6 +264,43 @@ affiliation: YC S25, raised $10M
Upload an image of your site to `public/showcase/website-name.png`
+## Before Opening a Pull Request
+
+Running the checks below locally first saves you a round trip with CI:
+
+1. **Run all checks**
+
+ ```bash
+ pnpm check
+ ```
+
+ This runs `lint`, `typecheck`, `format:check`, and `registry-deps:check` — four of the six CI gates. Most issues can be auto-fixed:
+
+ ```bash
+ pnpm lint:fix
+ pnpm format:fix
+ pnpm registry-deps:fix
+ ```
+
+ Note: `registry-deps:fix` updates `registry/registry-examples.ts`, so run `pnpm build:registry` afterwards to regenerate the artifacts.
+
+2. **Build the registry and commit the generated files** (see "6. Build registry" above) if you changed anything under `registry/` or `config/site.ts`.
+
+3. **Make sure the production build passes**
+
+ ```bash
+ pnpm build
+ ```
+
+ CI runs this too, and it is the slowest gate — catching a build break locally saves the longest round trip.
+
+4. **Use Conventional Commits** (enforced by local git hooks, not by CI)
+
+ Commit messages are validated by [commitlint](https://commitlint.js.org/) (e.g., `feat(marquee): add reverse prop`, `fix(globe): prevent crash on resize`). Use the same format for your PR title.
+
+> [!NOTE]
+> Git hooks (installed automatically with `pnpm i` via lefthook) run lint/format fixes on staged files and regenerate registry artifacts when you commit files under `registry/`, plus `typecheck` on push. They do not cover `registry-deps:check`, the production build, or a `config/site.ts`-only change — run `pnpm build:registry` yourself in that case.
+
## Ask for Help
For any help or questions, please open a new GitHub issue.
diff --git a/apps/www/scripts/sync-example-registry-dependencies.mts b/apps/www/scripts/sync-example-registry-dependencies.mts
index 951d0ebe..a7152045 100644
--- a/apps/www/scripts/sync-example-registry-dependencies.mts
+++ b/apps/www/scripts/sync-example-registry-dependencies.mts
@@ -655,6 +655,8 @@ async function main() {
if (blockingIssues.length > 0) {
console.error("registry example dependency mismatches found:")
console.error(blockingIssueSummary)
+ console.error("Run: pnpm registry-deps:fix && pnpm build:registry")
+ console.error("Then commit registry-examples.ts and the generated files.")
process.exit(1)
}
diff --git a/lefthook.yml b/lefthook.yml
index f1f257c6..75fcb7b0 100644
--- a/lefthook.yml
+++ b/lefthook.yml
@@ -3,10 +3,9 @@ pre-commit:
commands:
build:registry:
glob: "**/registry/**/*.{ts,tsx}"
- # www-scoped script only (the root build:registry also runs a
- # whole-project lint:fix + format:fix). Stage generated artifacts
- # by explicit path — never `git add --all`. CI's registry-drift job
- # checks these same paths, so a new artifact path can't slip through.
+ # Same regeneration-only command as the root build:registry script and
+ # CI's registry-drift job. Stage generated artifacts by explicit path —
+ # never `git add --all`. CI's registry-drift job checks these same paths.
run: >
pnpm --filter=www build:registry &&
git add apps/www/registry.json apps/www/registry/__index__.tsx
diff --git a/package.json b/package.json
index 1d9a9b17..bb368307 100644
--- a/package.json
+++ b/package.json
@@ -13,10 +13,10 @@
"lint:fix": "turbo run lint:fix",
"typecheck": "turbo run typecheck",
"format:fix": "turbo run format:fix",
- "format:fix:silent": "turbo run format:fix -- --log-level silent",
"format:check": "turbo run format:check",
"registry-deps:check": "pnpm --filter=www registry-deps:check",
- "build:registry": "pnpm --filter=www build:registry && pnpm --filter=www lint:fix && pnpm format:fix:silent",
+ "registry-deps:fix": "pnpm --filter=www registry-deps:fix",
+ "build:registry": "pnpm --filter=www build:registry",
"check": "pnpm lint && pnpm typecheck && pnpm format:check && pnpm registry-deps:check"
},
"devDependencies": {