editlet 0.1.0-alpha.0 → 0.1.0-alpha.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +74 -47
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,53 +1,62 @@
1
- # Editlet
1
+ <p align="center">
2
+ <img src="docs/assets/logo.svg" alt="Editlet logo" width="88" height="88">
3
+ </p>
2
4
 
3
- A Git-based, file-based CMS for Next.js and Astro. Content is Markdown files with YAML frontmatter in your repo,
4
- described by one `cms/schema.json`. Editors open `?editlet` on any page of the site, and every edit becomes a commit.
5
- Claude Code is the main editor, through the bundled skill.
5
+ <h1 align="center">Editlet</h1>
6
6
 
7
- Status: alpha (the npm dist-tag `alpha`: `editlet@alpha`). Node 22.12 or newer. Browsers: Chrome 125+, Edge 125+,
8
- Firefox 126+, Safari 17.5+. License: MIT.
7
+ <p align="center"><strong>Your agent writes. You merge.</strong><br>A small Git CMS for Next.js and Astro, with a skill for your coding agent.</p>
9
8
 
10
- ## Install with your agent
9
+ <p align="center">
10
+ <a href="https://editlet.gunkin.dev/docs/introduction"><strong>Docs</strong></a> ·
11
+ <a href="https://editlet.gunkin.dev/?editlet">Live demo</a> ·
12
+ <a href="#try-it-with-your-coding-agent">Get started</a> ·
13
+ <a href="#ai-coding-agents">AI agents</a>
14
+ </p>
11
15
 
12
- Copy this prompt into Claude Code, Codex or another coding agent, in your Next.js or Astro project:
16
+ <p align="center">
17
+ <a href="https://www.npmjs.com/package/editlet"><img src="https://img.shields.io/npm/v/editlet/alpha?label=npm&color=7c8cff&labelColor=101114" alt="npm version"></a>
18
+ <a href="https://editlet.gunkin.dev/docs/quick-start-next"><img src="https://img.shields.io/badge/Built_for-Next.js_·_Astro-7c8cff?labelColor=101114" alt="Built for Next.js and Astro"></a>
19
+ <a href="https://editlet.gunkin.dev/docs/content-model"><img src="https://img.shields.io/badge/Content_in-Git-7c8cff?labelColor=101114" alt="Content in Git"></a>
20
+ <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-7c8cff?labelColor=101114" alt="MIT license"></a>
21
+ </p>
22
+
23
+ Editlet keeps your content in your repository as Markdown with YAML frontmatter, described by one `cms/schema.json`.
24
+ Your coding agent edits it with the bundled skill, your team edits it with `?editlet` on any page of the site, and
25
+ every change is a pull request that a person merges.
26
+
27
+ > Early alpha: APIs may change between versions. Tested with Claude Code on Next.js and Astro.
28
+
29
+ <p align="center">
30
+ <a href="https://editlet.gunkin.dev"><img src="docs/assets/screenshot.png" alt="The Editlet homepage: Your agent writes. You merge." width="100%"></a>
31
+ </p>
32
+
33
+ ## Try it with your coding agent
34
+
35
+ Paste this into Claude Code, Codex or another coding agent in your Next.js or Astro project:
13
36
 
14
37
  ```text
15
38
  Install Editlet in this project: add the package `editlet@alpha` with the project's package manager, then read
16
39
  node_modules/editlet/skills/editlet-setup/SKILL.md and follow it.
17
40
  ```
18
41
 
19
- ## Install manually
42
+ 1. **Describe your content.** The agent writes `cms/schema.json` from your pages and wires the framework adapter.
43
+ 2. **Edit.** Ask the agent (`/editlet write a post about…`), or open `?editlet` on any page and edit next to the live
44
+ preview.
45
+ 3. **Merge.** Every edit is a commit on an `editlet/<name>` branch with a pull request. Nothing goes live until a
46
+ person merges it; the guard hook stops an agent from pushing to the base branch.
47
+
48
+ ## Install
20
49
 
21
50
  ```bash
22
51
  npm install editlet@alpha
23
52
  node node_modules/editlet/skills/editlet/scripts/link.mjs --hooks
24
53
  ```
25
54
 
26
- `link.mjs --hooks` links the skill into `.claude/skills/editlet` and `.agents/skills/editlet` and adds the guard hook.
27
- Run it again any time; with `--check --hooks` it only reports. Then add `cms/schema.json` and wire the framework as shown below
28
- (the agent's version of these steps is the `editlet-setup` skill in `skills/editlet-setup/`).
55
+ `link.mjs --hooks` links the skills into `.claude/skills/` and `.agents/skills/` and adds the guard hook. Run it again
56
+ any time; with `--check --hooks` it only reports. Then add `cms/schema.json` and wire the framework as shown below.
29
57
 
30
58
  `next`, `react` and `astro` are optional peer dependencies. Install the ones your framework needs: `next >=16` with
31
- `react >=19`, or `astro ^6 || ^7`.
32
-
33
- ## Entry points
34
-
35
- | Import | What it is |
36
- |---|---|
37
- | `editlet/next` | `createReader`, `EditletLoader` for Next.js Server Components |
38
- | `editlet/next/config` | `withEditlet` wrapper for `next.config.ts` |
39
- | `editlet/next/preview` | Draft-mode preview route (`POST`/`DELETE`) for `app/api/editlet/preview/route.ts` |
40
- | `editlet/astro` | Astro integration |
41
- | `editlet/astro/content` | `editletCollections`, `editletLoader` for `src/content.config.ts` |
42
- | `editlet/core` | Schema, entry parsing, validation, type generation (no Node or framework APIs) |
43
- | `editlet/node` | Local project reading and the dev file API |
44
- | `editlet/github` | GitHub content source: tree reads, commits, branches, PRs |
45
- | `editlet/auth` | GitHub OAuth handler (Cloudflare, Vercel, Node) |
46
- | `editlet/auth/client` | Browser side of the sign-in flow |
47
- | `editlet/auth/protocol` | Shared auth constants and types |
48
- | `editlet/loader` | The `?editlet` loader that mounts the editor iframe on a page |
49
- | `editlet/loader/protocol` | The `postMessage` protocol between page and admin |
50
- | `editlet/admin/dist/*` | The prebuilt admin app (static files) |
59
+ `react >=19`, or `astro ^6 || ^7`. Node 22.12 or newer.
51
60
 
52
61
  ## Next.js
53
62
 
@@ -69,8 +78,8 @@ export const { getEntries, getEntry, getRef } = createReader<EntryMap>();
69
78
  import { EditletLoader } from 'editlet/next';
70
79
  ```
71
80
 
72
- Add `/.editlet/` and `/public/editlet/` to `.gitignore`. More in the Next.js adapter README (`next/README.md` in the
73
- repository).
81
+ Add `/.editlet/` and `/public/editlet/` to `.gitignore`. Full guide:
82
+ [Quick start: Next.js](https://editlet.gunkin.dev/docs/quick-start-next).
74
83
 
75
84
  ## Astro
76
85
 
@@ -87,11 +96,13 @@ import { editletCollections } from 'editlet/astro/content';
87
96
  export const collections = editletCollections();
88
97
  ```
89
98
 
90
- Then use `getCollection`, `getEntry` and `render` as usual. More in the Astro adapter README (`astro/README.md`).
99
+ Then use `getCollection`, `getEntry` and `render` as usual. Full guide:
100
+ [Quick start: Astro](https://editlet.gunkin.dev/docs/quick-start-astro).
91
101
 
92
- ## Agent skills
102
+ ## AI coding agents
93
103
 
94
- The package ships three Agent Skills in `skills/`:
104
+ The package ships three Agent Skills in `skills/`, matching the installed version. Knowledge is delivered as files, so
105
+ there is no MCP server to run.
95
106
 
96
107
  | Skill | Use |
97
108
  |---|---|
@@ -99,16 +110,32 @@ The package ships three Agent Skills in `skills/`:
99
110
  | `editlet-setup` | Install Editlet in Next.js or Astro, set up editing on the live site, upgrade, diagnose (`doctor.mjs`) |
100
111
  | `editlet-migrate` | Import Markdown/MDX folders, Astro collections, Decap, TinaCMS, Keystatic and similar |
101
112
 
102
- ```bash
103
- node node_modules/editlet/skills/editlet/scripts/link.mjs --hooks
104
- ```
113
+ Check content with `node node_modules/editlet/skills/editlet/scripts/validate.mjs`. Full guide:
114
+ [The agent skills](https://editlet.gunkin.dev/docs/agent-skills).
115
+
116
+ ## Entry points
117
+
118
+ | Import | What it is |
119
+ |---|---|
120
+ | `editlet/next` | `createReader`, `EditletLoader` for Next.js Server Components |
121
+ | `editlet/next/config` | `withEditlet` wrapper for `next.config.ts` |
122
+ | `editlet/next/preview` | Draft-mode preview route (`POST`/`DELETE`) for `app/api/editlet/preview/route.ts` |
123
+ | `editlet/astro` | Astro integration |
124
+ | `editlet/astro/content` | `editletCollections`, `editletLoader` for `src/content.config.ts` |
125
+ | `editlet/core` | Schema, entry parsing, validation, type generation (no Node or framework APIs) |
126
+ | `editlet/node` | Local project reading and the dev file API |
127
+ | `editlet/github` | GitHub content source: tree reads, commits, branches, PRs |
128
+ | `editlet/auth` | GitHub OAuth handler (Cloudflare, Vercel, Node) |
129
+ | `editlet/auth/client` | Browser side of the sign-in flow |
130
+ | `editlet/auth/protocol` | Shared auth constants and types |
131
+ | `editlet/loader` | The `?editlet` loader that mounts the editor iframe on a page |
132
+ | `editlet/loader/protocol` | The `postMessage` protocol between page and admin |
133
+ | `editlet/admin/dist/*` | The prebuilt admin app (static files) |
134
+
135
+ Browsers: Chrome 125+, Edge 125+, Firefox 126+, Safari 17.5+.
105
136
 
106
- This links all three into `.claude/skills/` and `.agents/skills/` and adds the guard hook. Then ask your agent to set
107
- up Editlet. Check content with `node node_modules/editlet/skills/editlet/scripts/validate.mjs`. More in
108
- `skills/README.md`.
137
+ Documentation: https://editlet.gunkin.dev/docs/introduction
109
138
 
110
- ## Documentation
139
+ ## License
111
140
 
112
- The package source is published in [antongunkin/editlet](https://github.com/antongunkin/editlet).
113
- The full docs live in the development repository under `docs/`, which is not exported there yet, so module READMEs
114
- that link to `docs/` have dead links in the public repo. There is no public docs URL yet.
141
+ [MIT](LICENSE) © Anton Gunkin
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "editlet",
3
- "version": "0.1.0-alpha.0",
3
+ "version": "0.1.0-alpha.1",
4
4
  "description": "Git-based, file-based CMS for Next.js and Astro: Markdown content with YAML frontmatter and a schema in your repo, an editor overlay on your own site, every edit a commit.",
5
5
  "keywords": [
6
6
  "cms",