Skip to content

Commit fc350be

Browse files
author
robin
committed
docs: enhance plugin creation and installation instructions with scaffolding tool details
1 parent 1b836bb commit fc350be

2 files changed

Lines changed: 461 additions & 77 deletions

File tree

  • docs/development/plugins
  • i18n/zh-CN/docusaurus-plugin-content-docs/current/development/plugins

‎docs/development/plugins/plugin.md‎

Lines changed: 228 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,12 @@ Viewing the [**official plugin code**](https://github.com/apache/answer-plugins)
1313

1414
:::
1515

16+
:::info
17+
18+
**Recommended**: Use the official scaffolding tool [`create-answer-plugin`](https://www.npmjs.com/package/create-answer-plugin) to create and manage plugins. It automates most of the setup process, including file generation, Go module configuration, and plugin installation.
19+
20+
:::
21+
1622
## Introduction
1723

1824
### Plugin template types
@@ -52,66 +58,252 @@ The **name** field in package.json is the name of the package we add dependencie
5258

5359
:::
5460

55-
1. Go to the `ui > src > plugin` directory of the project.
61+
### Using the Scaffolding Tool (Recommended)
62+
63+
The easiest way to create a plugin is using the official scaffolding tool:
64+
65+
```shell
66+
# Install the tool globally (optional)
67+
npm install -g create-answer-plugin
68+
# or
69+
pnpm add -g create-answer-plugin
70+
71+
# Or use npx directly (recommended)
72+
npx create-answer-plugin create <pluginName>
73+
# or use the alias
74+
npx answer-plugin create <pluginName>
75+
# or use the simplified form
76+
npx answer-plugin <pluginName>
77+
```
78+
79+
**Note**: The package name is `create-answer-plugin`, but you can use either `create-answer-plugin` or `answer-plugin` as the command (both work!).
80+
81+
The tool will:
82+
1. Guide you through an interactive wizard to select the plugin type
83+
2. Generate all required files with the correct structure
84+
3. Create the Go wrapper file (required for Backend plugins)
85+
4. Set up proper `go.mod` with all dependencies
86+
5. Generate i18n files with the correct structure
5687

57-
2. Execute the following commands in that directory:
88+
**Options:**
89+
- `pluginName` (optional): Pre-fill the plugin name
90+
- `--path, -p`: Path to Answer project (root directory). If not specified, defaults to current directory.
5891

92+
**Example:**
5993
```shell
60-
npx create-answer-plugin <pluginName>
94+
# Navigate to your Answer project root
95+
cd /path/to/answer
96+
97+
# Create a plugin
98+
npx create-answer-plugin create my-plugin
99+
# or with path option
100+
npx create-answer-plugin create my-plugin --path /path/to/answer
101+
# Select: Standard UI Plugin → Route
102+
# Enter route path: /hello
61103
```
62104

63-
3. Select the type of plugin you want to create.
105+
The plugin will be created in `ui/src/plugins/my-plugin/` (note: `plugins` is plural).
106+
107+
### Manual Creation
108+
109+
If you prefer to create plugins manually:
110+
111+
1. Go to the `ui > src > plugins` directory of the project (note: `plugins` is plural).
112+
113+
2. Create your plugin directory and files following the structure of existing plugins.
64114

65115

66116

67117
## Run the Plugin
68118

69-
### Run the Backend Plugin
119+
### Install Plugin (Automated - Recommended)
120+
121+
The easiest way to install a plugin is using the scaffolding tool's `install` command:
122+
123+
```shell
124+
# Navigate to your Answer project root
125+
cd /path/to/answer
126+
127+
# Install a specific plugin (automatically handles registration)
128+
npx create-answer-plugin install my-plugin
129+
# or
130+
npx answer-plugin install my-plugin
131+
# or with path option
132+
npx answer-plugin install my-plugin --path /path/to/answer
133+
134+
# Install all not installed plugins
135+
npx create-answer-plugin install
136+
```
137+
138+
**Options:**
139+
- `plugins` (optional): Plugin names to install (defaults to all not installed plugins)
140+
- `--path, -p`: Path to Answer project (defaults to current directory)
141+
142+
The `install` command automatically:
143+
- ✅ Adds plugin import to `cmd/answer/main.go`
144+
- ✅ Adds `replace` directive to `go.mod`
145+
- ✅ Runs `go mod tidy`
146+
- ✅ Merges i18n resources using `go run ./cmd/answer/main.go i18n`
147+
148+
### List Plugins
149+
150+
List all plugins in the Answer project:
151+
152+
```shell
153+
# List all plugins
154+
npx create-answer-plugin list
155+
# or
156+
npx answer-plugin list
157+
# or with path option
158+
npx answer-plugin list /path/to/answer
159+
```
70160

71-
1. First, execute `make ui` to compile the front-end code.
72-
2. In the `cmd > answer > main.go` file, import your plugin.
161+
**Options:**
162+
- `path` (optional): Path to Answer project (defaults to current directory)
73163

74-
```go
75-
import (
76-
answercmd "github.com/apache/answer/cmd"
164+
### Uninstall Plugins
77165

78-
// Import the plugins
79-
_ "github.com/apache/answer-plugins/my-plugin"
80-
)
81-
```
82-
3. Use `go mod edit` to add the plugin to the `go.mod` file.
166+
Uninstall plugins from the Answer project:
83167

84-
```shell
85-
go mod edit -replace=github.com/apache/answer-plugins/my-plugin=./ui/src/plugins/my-plugin
86-
```
87-
4. Update the dependencies.
168+
```shell
169+
# Uninstall all installed plugins
170+
npx create-answer-plugin uninstall
171+
# or
172+
npx answer-plugin uninstall
173+
174+
# Uninstall specific plugins
175+
npx create-answer-plugin uninstall my-plugin another-plugin
176+
# or with path option
177+
npx answer-plugin uninstall my-plugin --path /path/to/answer
178+
```
88179

89-
```shell
90-
go mod tidy
91-
```
180+
**Options:**
181+
- `plugins` (optional): Plugin names to uninstall (defaults to all installed plugins)
182+
- `--path, -p`: Path to Answer project (defaults to current directory)
92183

93-
5. Start the project.
184+
The `uninstall` command automatically:
185+
- ✅ Removes plugin import from `cmd/answer/main.go`
186+
- ✅ Removes `replace` directive from `go.mod`
187+
- ✅ Runs `go mod tidy`
188+
- ✅ Updates i18n resources
94189

95-
```shell
96-
go run cmd/answer/main.go run -C ./answer-data
97-
```
190+
### Run the Backend Plugin
191+
192+
#### Using the Scaffolding Tool (Recommended)
193+
194+
1. Install the plugin using the scaffolding tool (see above).
195+
196+
2. Build the frontend:
197+
```shell
198+
cd ui
199+
pnpm pre-install
200+
pnpm build
201+
cd ..
202+
```
203+
204+
3. Merge i18n resources (if not done automatically):
205+
```shell
206+
go run ./cmd/answer/main.go i18n
207+
```
208+
209+
4. Start the project:
210+
```shell
211+
go run cmd/answer/main.go run -C ./answer-data
212+
```
213+
214+
#### Manual Installation
215+
216+
If you prefer to install manually:
217+
218+
1. First, build the frontend:
219+
```shell
220+
cd ui
221+
pnpm pre-install
222+
pnpm build
223+
cd ..
224+
```
225+
226+
2. In the `cmd > answer > main.go` file, import your plugin:
227+
```go
228+
import (
229+
answercmd "github.com/apache/answer/cmd"
230+
231+
// Import the plugins
232+
_ "github.com/apache/answer/ui/src/plugins/my-plugin"
233+
)
234+
```
235+
236+
3. Use `go mod edit` to add the plugin to the `go.mod` file:
237+
```shell
238+
go mod edit -replace=github.com/apache/answer/ui/src/plugins/my-plugin=./ui/src/plugins/my-plugin
239+
```
240+
241+
4. Update the dependencies:
242+
```shell
243+
go mod tidy
244+
```
245+
246+
5. Merge i18n resources:
247+
```shell
248+
go run ./cmd/answer/main.go i18n
249+
```
250+
251+
6. Start the project:
252+
```shell
253+
go run cmd/answer/main.go run -C ./answer-data
254+
```
98255

99256
### Run the Standard UI Plugin
100257

101-
1. Go to the `ui` directory.
102-
2. Install the dependencies.
258+
#### Using the Scaffolding Tool (Recommended)
103259

104-
```shell
105-
pnpm pre-install
106-
```
260+
1. Install the plugin using the scaffolding tool:
261+
```shell
262+
cd /path/to/answer
263+
npx create-answer-plugin install my-plugin
264+
```
107265

108-
3. Start the project.
266+
2. Go to the `ui` directory and install dependencies:
267+
```shell
268+
cd ui
269+
pnpm pre-install
270+
```
109271

110-
```shell
111-
pnpm start
112-
```
272+
3. Build the frontend:
273+
```shell
274+
pnpm build
275+
```
113276

114-
4. Refer to the [Run the Backend Plugin](/docs/development/plugins#debugging-plugins) and add the plugin to the project.
277+
4. For development, start the dev server:
278+
```shell
279+
pnpm start
280+
```
281+
282+
5. Merge i18n resources (if not done automatically):
283+
```shell
284+
cd ..
285+
go run ./cmd/answer/main.go i18n
286+
```
287+
288+
#### Manual Installation
289+
290+
1. Go to the `ui` directory.
291+
2. Install the dependencies:
292+
```shell
293+
pnpm pre-install
294+
```
295+
296+
3. Build the frontend:
297+
```shell
298+
pnpm build
299+
```
300+
301+
4. For development, start the dev server:
302+
```shell
303+
pnpm start
304+
```
305+
306+
5. Refer to the [Run the Backend Plugin](/docs/development/plugins#run-the-backend-plugin) section and manually add the plugin to the project (import in `main.go`, add `replace` directive, etc.).
115307

116308
## Backend Plugin Development
117309

0 commit comments

Comments
 (0)