From 033782f9a2226dd0a3a2aa418614456527144ad1 Mon Sep 17 00:00:00 2001 From: neverland Date: Wed, 19 Aug 2026 21:54:08 +0800 Subject: [PATCH] docs(website): add IDE integration guide --- scripts/dictionary.txt | 1 + website/docs/en/guide/_meta.json | 5 ++ website/docs/en/guide/ide-integration.mdx | 85 +++++++++++++++++++++++ website/docs/zh/guide/_meta.json | 5 ++ website/docs/zh/guide/ide-integration.mdx | 85 +++++++++++++++++++++++ 5 files changed, 181 insertions(+) create mode 100644 website/docs/en/guide/ide-integration.mdx create mode 100644 website/docs/zh/guide/ide-integration.mdx diff --git a/scripts/dictionary.txt b/scripts/dictionary.txt index 06b17167..7eb7d9b1 100644 --- a/scripts/dictionary.txt +++ b/scripts/dictionary.txt @@ -30,6 +30,7 @@ rstest shiki shikijs solidjs +Trae turborepo typicode worktank diff --git a/website/docs/en/guide/_meta.json b/website/docs/en/guide/_meta.json index 630bde07..c8316513 100644 --- a/website/docs/en/guide/_meta.json +++ b/website/docs/en/guide/_meta.json @@ -47,6 +47,11 @@ "name": "monorepo", "label": "Monorepo" }, + { + "type": "file", + "name": "ide-integration", + "label": "IDE integration" + }, { "type": "dir-section-header", "name": "cli", diff --git a/website/docs/en/guide/ide-integration.mdx b/website/docs/en/guide/ide-integration.mdx new file mode 100644 index 00000000..f85630b2 --- /dev/null +++ b/website/docs/en/guide/ide-integration.mdx @@ -0,0 +1,85 @@ +--- +description: 'Set up the official Rstack extension for linting, formatting, and testing in VS Code.' +--- + +# IDE integration + +Rstack currently provides official VS Code integration through the [Rstack extension](https://github.com/rstackjs/rstack-editor). The extension brings Rstack CLI's linting, formatting, and testing capabilities into the editor. + +## Installation + +Install `Rstack` from the registry for your editor: + +- [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=rstack.rstack) for VS Code. +- [Open VSX Registry](https://open-vsx.org/extension/rstack/rstack) for Cursor, VSCodium, Trae, and other VS Code-compatible editors. + +You can also search for the extension identifier `rstack.rstack` in your editor's Extensions view. + +> The extension does not bundle Rstack CLI. It uses the `rstack` package installed in the project's `node_modules`. Install the project dependencies first so the editor and CLI use the same Rstack CLI version. + +## Configuration + +To use Rstack as the default formatter and format files on save, add the following settings: + +```json title=".vscode/settings.json" +{ + "editor.defaultFormatter": "rstack.rstack", + "[javascript]": { + "editor.defaultFormatter": "rstack.rstack" + }, + "[javascriptreact]": { + "editor.defaultFormatter": "rstack.rstack" + }, + "[typescript]": { + "editor.defaultFormatter": "rstack.rstack" + }, + "[typescriptreact]": { + "editor.defaultFormatter": "rstack.rstack" + }, + "editor.formatOnSave": true +} +``` + +The language-specific JavaScript and TypeScript settings prevent existing formatter preferences from overriding the workspace default. + +To apply lint fixes when you save a file manually, add: + +```json title=".vscode/settings.json" +{ + "editor.codeActionsOnSave": { + "source.fixAll.rslint": "explicit" + } +} +``` + +> `"explicit"` applies lint fixes only on manual saves. Use `"always"` to apply them during auto-save as well. + +To recommend the extension to team members who open the repository, add it to the workspace recommendations: + +```json title=".vscode/extensions.json" +{ + "recommendations": ["rstack.rstack"] +} +``` + +## Features + +### Linting + +Shows lint diagnostics as you edit, provides quick fixes, and fixes issues on save. + +### Formatting + +Formats documents through the project-local [`rs fmt`](./cli/fmt) language server. It loads `define.fmt()` from [`rstack.config.*`](./configuration#configuration-file) at the workspace root, keeping the editor and CLI on the same formatting rules. + +### Testing + +Adds project tests to VS Code's Test Explorer. You can run or debug an individual test, suite, or file, and failed tests also appear as editor diagnostics. + +## Troubleshooting + +The `Rstack` status bar item shows the active features and their status, including configuration discovery and version compatibility problems. If its status does not update after installing dependencies or editing configuration, open the Command Palette and run `Rstack: Relaunch Extension`. + +For more usage details, see the [extension documentation](https://github.com/rstackjs/rstack-editor/blob/main/packages/vscode/README.md). + +Report bugs and feature requests through [Rstack Editor Issues](https://github.com/rstackjs/rstack-editor/issues). diff --git a/website/docs/zh/guide/_meta.json b/website/docs/zh/guide/_meta.json index 518da9ca..1c7c16cb 100644 --- a/website/docs/zh/guide/_meta.json +++ b/website/docs/zh/guide/_meta.json @@ -47,6 +47,11 @@ "name": "monorepo", "label": "Monorepo" }, + { + "type": "file", + "name": "ide-integration", + "label": "IDE 集成" + }, { "type": "dir-section-header", "name": "cli", diff --git a/website/docs/zh/guide/ide-integration.mdx b/website/docs/zh/guide/ide-integration.mdx new file mode 100644 index 00000000..1067f8bc --- /dev/null +++ b/website/docs/zh/guide/ide-integration.mdx @@ -0,0 +1,85 @@ +--- +description: '介绍如何在 VS Code 中使用 Rstack 官方扩展进行代码检查、格式化和测试。' +--- + +# IDE 集成 \{#ide-integration} + +Rstack 目前通过 [Rstack 扩展](https://github.com/rstackjs/rstack-editor) 提供官方的 VS Code 集成。该扩展将 Rstack CLI 的代码检查、格式化和测试能力集成到编辑器中。 + +## 安装 \{#installation} + +根据所用编辑器，从对应的扩展市场安装 `Rstack`： + +- VS Code 用户从 [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=rstack.rstack) 安装。 +- Cursor、VSCodium、Trae 及其他兼容 VS Code 的编辑器用户从 [Open VSX Registry](https://open-vsx.org/extension/rstack/rstack) 安装。 + +也可以在编辑器的扩展视图中搜索扩展标识 `rstack.rstack`。 + +> 扩展本身不内置 Rstack CLI，而是使用项目 `node_modules` 中安装的 `rstack` 包。请先安装项目依赖，以确保编辑器和 CLI 使用相同版本的 Rstack CLI。 + +## 配置 \{#configuration} + +要将 Rstack 设为默认格式化工具，并在保存文件时执行格式化，请添加以下配置： + +```json title=".vscode/settings.json" +{ + "editor.defaultFormatter": "rstack.rstack", + "[javascript]": { + "editor.defaultFormatter": "rstack.rstack" + }, + "[javascriptreact]": { + "editor.defaultFormatter": "rstack.rstack" + }, + "[typescript]": { + "editor.defaultFormatter": "rstack.rstack" + }, + "[typescriptreact]": { + "editor.defaultFormatter": "rstack.rstack" + }, + "editor.formatOnSave": true +} +``` + +其中，针对 JavaScript 和 TypeScript 的语言级配置可以避免开发者已有的格式化设置覆盖工作区默认值。 + +如需在手动保存文件时同时修复代码检查问题，可以添加： + +```json title=".vscode/settings.json" +{ + "editor.codeActionsOnSave": { + "source.fixAll.rslint": "explicit" + } +} +``` + +> `"explicit"` 表示仅在手动保存时应用代码检查修复；如需在自动保存时也执行修复，可以改为 `"always"`。 + +若希望团队成员打开仓库时收到安装建议，可以将该扩展添加到工作区推荐列表： + +```json title=".vscode/extensions.json" +{ + "recommendations": ["rstack.rstack"] +} +``` + +## 支持能力 \{#features} + +### 代码检查 \{#linting} + +在编辑过程中显示代码检查诊断、提供快速修复，并支持保存时修复。 + +### 格式化 \{#formatting} + +扩展会通过项目本地的 [`rs fmt`](./cli/fmt) language server 格式化文档，并读取工作区根目录 [`rstack.config.*`](./configuration#configuration-file) 中的 `define.fmt()` 配置，使编辑器与 CLI 使用一致的格式化规则。 + +### 测试 \{#testing} + +将项目测试添加到 VS Code 的测试资源管理器。你可以运行或调试单个测试、测试套件或测试文件，失败的测试也会显示为编辑器诊断信息。 + +## 排查问题 \{#troubleshooting} + +状态栏中的 `Rstack` 项会显示当前启用的功能及其状态，并提示配置发现或版本兼容问题。如果安装依赖或修改配置后状态未更新，请打开命令面板并运行 `Rstack: Relaunch Extension`。 + +更多用法请参阅[扩展文档](https://github.com/rstackjs/rstack-editor/blob/main/packages/vscode/README.md)。 + +如需报告问题或提出功能建议，请前往 [Rstack Editor Issues](https://github.com/rstackjs/rstack-editor/issues)。