From 0461460e5d6b869a40bf66d756aea2624c86677f Mon Sep 17 00:00:00 2001 From: Hong Minhee Date: Mon, 27 Apr 2026 21:05:14 +0900 Subject: [PATCH 1/3] Document editor setup, lint plugin, and Agentic Skill in install guide The installation page covered fedify init and manual JSR/npm installation only. Three new sections at the bottom close common post-install questions: - "Editor setup" shows the .vscode/ files fedify init writes for Deno and Node.js/Bun projects, points Zed users at the snippets they need to add by hand, and notes Oxc as an alternative to Biome and ESLint. - "Linting" is a short bridge that mentions the @fedify/lint plugin is wired up automatically and links to the Linting chapter for the rest. - "Agentic skill" documents the SKILL.md bundled inside @fedify/fedify starting with Fedify 2.2.0: skills-npm + a prepare script for Node.js/Bun, manual download via curl for Deno (with a forward pointer to the Claude Code plugin marketplace work). https://github.com/fedify-dev/fedify/issues/711 https://github.com/fedify-dev/fedify/pull/712 https://github.com/fedify-dev/fedify/issues/489 Assisted-by: Claude Code:claude-opus-4-7 --- docs/install.md | 255 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 255 insertions(+) diff --git a/docs/install.md b/docs/install.md index b8e1c8c14..40bc39bf9 100644 --- a/docs/install.md +++ b/docs/install.md @@ -185,3 +185,258 @@ compatibility, ESM is the preferred approach: [ESM]: https://nodejs.org/api/esm.html [CommonJS]: https://nodejs.org/docs/latest/api/modules.html + + +Editor setup +------------ + +`fedify init` configures Visual Studio Code for you out of the box. Setting +up [Zed] takes a few extra steps because `fedify init` does not generate +*.zed/* files yet. + +[Zed]: https://zed.dev/ + +### Visual Studio Code + +*For Deno projects*, `fedify init` writes a *.vscode/extensions.json* that +recommends the [Deno extension]: + +~~~~ json [.vscode/extensions.json] +{ "recommendations": ["denoland.vscode-deno"] } +~~~~ + +The matching *.vscode/settings.json* turns on Deno's language server and sets +it as the default formatter for JavaScript and TypeScript: + +~~~~ jsonc [.vscode/settings.json] +{ + "deno.enable": true, + "deno.unstable": true, + "editor.detectIndentation": false, + "editor.indentSize": 2, + "editor.insertSpaces": true, + "[typescript]": { + "editor.defaultFormatter": "denoland.vscode-deno", + "editor.formatOnSave": true, + "editor.codeActionsOnSave": { + "source.sortImports": "always" + } + } + // The same block applies to [javascript], [javascriptreact], and + // [typescriptreact]; [json] and [jsonc] use "vscode.json-language-features". +} +~~~~ + +Deno's [*Set up your environment*] guide covers other editors and shells. + +*For Node.js/Bun projects*, `fedify init` writes a *.vscode/extensions.json* +that recommends the [Biome extension] and the [ESLint extension]: + +~~~~ json [.vscode/extensions.json] +{ "recommendations": ["biomejs.biome", "dbaeumer.vscode-eslint"] } +~~~~ + +The matching *.vscode/settings.json* sets Biome as the default formatter and +runs Biome's import organiser on save: + +~~~~ jsonc [.vscode/settings.json] +{ + "editor.detectIndentation": false, + "editor.indentSize": 2, + "editor.insertSpaces": true, + "[typescript]": { + "editor.defaultFormatter": "biomejs.biome", + "editor.formatOnSave": true, + "editor.codeActionsOnSave": { + "source.organizeImports.biome": "always" + } + } + // The same block applies to [javascript], [javascriptreact], + // [typescriptreact], [json], and [jsonc]. +} +~~~~ + +If you prefer [Oxc] over Biome and ESLint, install the [oxc-vscode] +extension and swap the formatter: + +~~~~ jsonc [.vscode/settings.json] +{ + "[typescript]": { + "editor.defaultFormatter": "oxc.oxc-vscode", + "editor.formatOnSave": true, + "editor.codeActionsOnSave": { + "source.fixAll.oxc": "always" + } + } +} +~~~~ + +[Deno extension]: https://marketplace.visualstudio.com/items?itemName=denoland.vscode-deno +[*Set up your environment*]: https://docs.deno.com/runtime/getting_started/setup_your_environment/ +[Biome extension]: https://marketplace.visualstudio.com/items?itemName=biomejs.biome +[ESLint extension]: https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint +[Oxc]: https://oxc.rs/ +[oxc-vscode]: https://marketplace.visualstudio.com/items?itemName=oxc.oxc-vscode + +### Zed + +> [!TIP] +> `fedify init` does not generate *.zed/* configuration; the snippets below +> need to be added by hand. + +*For Deno projects*, create *.zed/settings.json* that enables the Deno +language server and uses it as the formatter for TypeScript and JavaScript. +The `!` prefix disables the bundled TypeScript and ESLint servers so they do +not compete with Deno: + +~~~~ jsonc [.zed/settings.json] +{ + "lsp": { + "deno": { + "settings": { "deno": { "enable": true } } + } + }, + "languages": { + "TypeScript": { + "formatter": [ + { "language_server": { "name": "deno" } } + ], + "language_servers": [ + "deno", + "!typescript-language-server", + "!vtsls", + "!eslint", + "!biome", + "..." + ] + } + // The same block applies to TSX and JavaScript. + } +} +~~~~ + +Zed's [Deno language docs][zed-deno] cover the available options. +[Hackers' Pub] is a real-world reference. + +*For Node.js/Bun projects*, Zed enables its bundled TypeScript language +server out of the box; the typical addition is wiring up Biome (or the +formatter you chose) for `editor.formatOnSave`-style behaviour. See Zed's +[TypeScript language docs][zed-ts] for setup. If you prefer [Oxc] instead, +set Oxc as the language server and turn on its fix-all action on format: + +~~~~ jsonc [.zed/settings.json] +{ + "language_servers": ["oxc", "..."], + "code_actions_on_format": { + "source.fixAll.oxc": true + } +} +~~~~ + +[zed-deno]: https://zed.dev/docs/languages/deno +[Hackers' Pub]: https://github.com/hackers-pub/hackerspub/blob/main/.zed/settings.json +[zed-ts]: https://zed.dev/docs/languages/typescript + + +Linting +------- + +`fedify init` configures the [`@fedify/lint`] plugin automatically: Deno +projects pick it up through `lint.plugins` in *deno.json*, and Node.js/Bun +projects through a generated *eslint.config.ts*. For the full rule list, +configuration options, and how to run the linter, see the +[*Linting*](./manual/lint.md) chapter. + +[`@fedify/lint`]: https://jsr.io/@fedify/lint + + +Agentic skill +------------- + +_This skill is available since Fedify 2.2.0._ + +Fedify ships a [Markdown skill file][SKILL.md] that AI coding assistants such +as [Claude Code], [Codex], or [OpenCode] can load to learn Fedify's APIs, +common pitfalls, and recommended patterns. The file lives inside the +`@fedify/fedify` package itself, so the only remaining step is exposing it +to your agent's skills directory. + +[SKILL.md]: https://github.com/fedify-dev/fedify/blob/main/packages/fedify/skills/fedify/SKILL.md +[Claude Code]: https://claude.com/product/claude-code +[Codex]: https://developers.openai.com/codex +[OpenCode]: https://opencode.ai/ + +### Node.js/Bun + +Use [`skills-npm`], a third-party tool by Anthony Fu (it is not a Fedify +package), that scans *node\_modules* for packages exposing the `agents.skills` +field in their *package.json* and links them into your agent's skills +directory on every install. + +1. Install `skills-npm` as a dev dependency: + + ::: code-group + + ~~~~ sh [npm] + npm add -D skills-npm + ~~~~ + + + ~~~~ sh [pnpm] + pnpm add -D skills-npm + ~~~~ + + + ~~~~ sh [Yarn] + yarn add -D skills-npm + ~~~~ + + + ~~~~ sh [Bun] + bun add -D skills-npm + ~~~~ + + ::: + +2. Add a `prepare` script to your *package.json* so it runs after every + install: + + ~~~~ json + { + "scripts": { + "prepare": "skills-npm" + } + } + ~~~~ + +3. Reinstall once. The Fedify skill appears at *.claude/skills/fedify/* + (and similar locations for other supported agents). + +The same script picks up other Fedify packages and any third-party npm +packages that adopt the convention. + +[`skills-npm`]: https://github.com/antfu/skills-npm + +### Deno + +> [!NOTE] +> Automated installation for Deno is not available yet, so the skill must be +> installed by hand for the time being. Future automation through the +> Claude Code plugin marketplace is tracked in +> [issue #489]. + +1. Pick your agent's skills directory. For Claude Code, this is + *.claude/skills/fedify/*. + +2. Download *SKILL.md* from the Fedify repository: + + ~~~~ sh + mkdir -p .claude/skills/fedify + curl -L -o .claude/skills/fedify/SKILL.md \ + https://raw.githubusercontent.com/fedify-dev/fedify/main/packages/fedify/skills/fedify/SKILL.md + ~~~~ + +3. Either commit the file or add it to *.gitignore*, depending on your + team's preference. + +[issue #489]: https://github.com/fedify-dev/fedify/issues/489 From 3e331396d3450c45ab948e87b5b94f32d996ad52 Mon Sep 17 00:00:00 2001 From: Hong Minhee Date: Mon, 27 Apr 2026 21:12:16 +0900 Subject: [PATCH 2/3] Update fedify init demo video in documentation The asciinema demo video for the fedify init command was outdated due to recent UI changes. This commit updates the documentation to link to the newly recorded video (ID: 979416). Assisted-by: Gemini CLI:gemini-2.0-flash-exp --- docs/cli.md | 2 +- docs/install.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/cli.md b/docs/cli.md index 5074d0152..7658146b1 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -216,7 +216,7 @@ precedence over configuration file values. *This command is available since Fedify 0.12.0.* -[![The “fedify init” command demo](https://asciinema.org/a/671658.svg)](https://asciinema.org/a/671658) +[![The “fedify init” command demo](https://asciinema.org/a/979416.svg)](https://asciinema.org/a/979416) The `fedify init` command is used to initialize a new Fedify project. It creates a new directory with the necessary files and directories for a diff --git a/docs/install.md b/docs/install.md index 40bc39bf9..765abd4d5 100644 --- a/docs/install.md +++ b/docs/install.md @@ -66,7 +66,7 @@ For more information about the `fedify init` command, please refer to the [*`fedify init`* section](./cli.md#fedify-init-initializing-a-fedify-project) in the *CLI toolchain* docs. -[![The “fedify init” command demo](https://asciinema.org/a/671658.svg)](https://asciinema.org/a/671658) +[![The “fedify init” command demo](https://asciinema.org/a/979416.svg)](https://asciinema.org/a/979416) ### Alternative: Using `@fedify/create` From ffa09c82759837449e2d62c8f8dbfdee91c678d4 Mon Sep 17 00:00:00 2001 From: Hong Minhee Date: Mon, 27 Apr 2026 21:15:19 +0900 Subject: [PATCH 3/3] Add mise installation instructions for fedify CLI Users can now install the fedify CLI tool using mise by running `mise use -g github:fedify-dev/fedify`. This commit adds the corresponding instructions to the CLI documentation. Assisted-by: Gemini CLI:gemini-2.0-flash-exp --- docs/cli.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/cli.md b/docs/cli.md index 7658146b1..a724338f2 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -99,6 +99,17 @@ command above. [Deno]: https://deno.com/ +### Using mise + +If you have [mise] installed, you can install `fedify` by running the following +command: + +~~~~ sh +mise use -g github:fedify-dev/fedify +~~~~ + +[mise]: https://mise.jdx.dev/ + ### Downloading the executable You can download the pre-built executables from the [releases] page. Download