npm - @modern-js/main-doc - Versions diffs - 2.60.6 → 2.61.0 - Mend

@modern-js/main-doc 2.60.6 → 2.61.0

Files changed (55) hide show

package/docs/en/guides/topic-detail/generator/plugin/api/onForged.md DELETED Viewed

@@ -1,310 +0,0 @@
----
-sidebar_position: 2
----
-# onForged
-`onForged` is a lifecycle function used for file operations in generator plugin.
-## Types
-```ts
-export type ForgedAPI = {
-  addFile: (params: AddFileParams) => Promise<void>;
-  addManyFiles: (params: AddManyFilesParams) => Promise<void>;
-  updateJSONFile: (fileName: string, updateInfo: Record<string, unknown>) => Promise<void>;
-  updateTextRawFile: (fileName: string, update: (content: string[]) => string[]) => Promise<void>;
-  updateModernConfig: (updateInfo: Record<string, any>) => Promise<void>;
-  rmFile: (fileName: string) => Promise<void>;
-  rmDir: (dirName: string) => Promise<void>;
-  addHelper: (name: string, fn: Handlebars.HelperDelegate) => void;
-  addPartial: (name: string, str: Handlebars.Template) => void;
-  createElement: (element: ActionElement, params: Record<string, unknown>) => Promise<void>;
-  enableFunc: (func: ActionFunction, params?: Record<string, unknown> | undefined) => Promise<void>;
-};
-export type PluginForgedFunc = (
-  api: ForgedAPI,
-  inputData: Record<string, unknown>,
-) => void | Promise<void>;
-export interface IPluginContext {
-  onForged: (func: PluginForgedFunc) => void;
-  ...
-}
-```
-The `onForged` parameter is a callback function with `api` and `input` as parameters, which are used to provide the APIs and current input information provided by the lifecycle function.
-## Concepts
-### File Types
-The generator plugin classifies files into four categories:
-- Text files
-Files with pure text content that can be processed using [Handlebars](https://handlebarsjs.com/) or [EJS](https://ejs.co/) templates.
-- Binary files
-Files such as images, audio, and video.
-- JSON files
-Files in JSON format.
-- Text list files
-Files composed of lines of text, such as `.gitignore`, `.editorconfig`, and `.npmrc`.
-The type definitions for the four types of files are:
-```ts
-export enum FileType {
-  Text = 'text',
-  Binary = 'binary',
-  Json = 'json',
-  TextRaw = 'textRaw',
-}
-```
-## API
-The APIs provided by the `api` parameter will be introduced below.
-### addFile
-Adds a single file.
-Parameter types:
-```ts
-export interface AddFileParams {
-  type: FileType;
-  file: string;
-  template?: string;
-  templateFile?: string;
-  force?: boolean;
-  data?: Record<string, string>;
-}
-```
-- `type`: File type.
-- `file`: Target file path, relative to the target project directory.
-- `template`: Template content, the value of this field can be directly used to render the file. Lower priority than `templateFile`.
-- `templateFile`: Template file path, relative to the templates directory.
-- `force`: Whether to force overwrite when the target file exists, default is false.
-- `data`: Template rendering data.
-:::info
-Text files are processed using Handlebars by default. If the template file ends with `.ejs`, [EJS](https://ejs.co/) will be used for template rendering.
-:::
-For example, add the template file `App.tsx.hanlebars` to `src/App.tsx`:
-```ts
-context.onForged(async (api: ForgedAPI, _input: Record<string, unknown>) => {
-  await api.addFile({
-    type: FileType.Text,
-    file: `src/App.tsx`,
-    templateFile: `App.tsx.handlebars`,
-  });
-})
-```
-### addManyFiles
-Adds multiple files, usually used to add multiple files to the same target directory.
-Parameter types:
-```ts
-export interface AddManyFilesParams {
-  type: FileType;
-  destination: string;
-  templateFiles: string[] | (() => string[]);
-  templateBase?: string;
-  fileNameFunc?: (name: string) => string;
-  data?: Record<string, string>;
-}
-```
-- `type`: File type.
-- `destination`: Target folder, relative path to the target project directory.
-- `templateFiles`: Template file list, supporting regular expressions from [globby](https://www.npmjs.com/package/globby).
-- `templateBase`: Common path of template files. When using this parameter, the target file will automatically delete this path.
-- `fileNameFunc`: Function to rename files. During the file addition process, the file name will be passed to this function in turn, and the renaming can be performed as needed.
-- `data`: Template rendering data.
-For example, render all files in the `src-ts` directory of the template file to the `src` directory:
-```ts
-context.onForged(async (api: ForgedAPI, _input: Record<string, unknown>) => {
-  await api.addManyFiles({
-    type: FileType.Text,
-    destination: 'src',
-    templateFiles: ['src-ts/**/*'],
-    templateBase: 'src-ts',
-    fileNameFunc: name => name.replace('.handlebars', ''),
-  });
-})
-```
-### updateJSONFile
-Update fields in a JSON file.
-Parameter types:
-```ts
-fileName: strings
-updateInfo: Record<string, unknown>
-```
-- `fileName`: JSON file path, relative to the target project path.
-- `updateInfo`: Update information. Nested field updates need to be flattened, otherwise the entire update will cause content loss.
-For example, update the `name` field of `package.json`:
-```ts
-context.onForged(async (api: ForgedAPI, _input: Record<string, unknown>) => {
-  await api.updateJSONFile('package.json', { name: 'new_name' });
-})
-```
-For example, update the version of `react-dom` in `dependencies`:
-```ts
-context.onForged(async (api: ForgedAPI, _input: Record<string, unknown>) => {
-  await api.updateJSONFile('package.json', {
-    'dependencies.react-dom': '^18',
-  });
-})
-```
-### updateTextRawFile
-Update the contents of a text list file.
-Parameter types:
-```ts
-fileName: string
-update: (content: string[]) => string[]
-```
-- `fileName`: Text list file path, relative to the target project path.
-- `update`: Update function. The parameter is an array divided by `\n` of the current file content, and the return value is also the modified array after modification. `@modern-js/create` will automatically merge it with `\n` and write it to the source file.
-For example, add the `dist` directory to the `.gitinore` file:
-```ts
-context.onForged(async (api: ForgedAPI, _input: Record<string, unknown>) => {
-  await api.updateTextRawFile('.gitinore', (content) => [...content, 'dist']);
-})
-```
-### updateModernConfig (not recommended)
-In addition to configuring in `modern.config.[tj]s`, Modern.js configuration also supports configuring `modernConfig` in `package.json`. This function is used to update this field.
-Parameter types:
-```ts
-updateInfo: Record<string, any>
-```
-- `updateInfo`: Update content information. `updateModernConfig` is a package based on `updateJSONFile`, which will automatically update under the `modernConfig` field. Only the configuration fields under `modernConfig` need to be filled in `updateInfo`.
-For example, enable SSR:
-```ts
-context.onForged(async (api: ForgedAPI, _input: Record<string, unknown>) => {
-  await api.updateModernConfig({ 'server.ssr': true });
-})
-```
-### rmFile
-Delete files.
-Parameter types:
-```ts
-fileName: string
-```
-- `fileName`: The path of the file to be deleted, relative to the target project path.
-### rmDir
-Delete a folder.
-Parameter types:
-```ts
-dirName: string
-```
-- `dirName`: The path of the folder to be deleted, relative to the target project path.
-### addHelper
-Add a [custom helper](https://handlebarsjs.com/guide/#custom-helpers) rendered by handlebrs.
-Parameter types:
-```ts
-name: string
-fn: Handlebars.HelperDelegate
-```
-- `name`: Helper function name.
-- `fn`: Helper function implementation.
-### addPartial
-Add a [Partial](https://handlebarsjs.com/guide/partials.html#basic-partials) rendered by Handlebars.
-Parameter types:
-```ts
-name: string
-str: Handlebars.Template
-```
-- `name`: Partial name.
-- `str`: Template string of the Partial.
-### createElement
-Automatically run the `new` command to create project elements.
-Parameter types:
-```ts
-element: ActionElement
-params: Record<string, unknown>
-```
-- `element`: Type of project element, new entry or new custom Web Server source directory.
-- `params`: Other parameters corresponding to creating project elements.
-### enableFunc
-Automatically run the `new` command to enable optional features.
-Parameter types:
-```ts
-func: ActionFunction
-params?: Record<string, unknown>
-```
-- `func`: Name of the feature to enable.
-- `params`: Other parameters corresponding to enabling the feature.
-:::info
-Refer to [Configuration Parameters](/guides/topic-detail/generator/new/config.html) for creating project elements and enabling feature configurations.
-:::

package/docs/en/guides/topic-detail/generator/plugin/category.md DELETED Viewed

@@ -1,88 +0,0 @@
----
-sidebar_position: 2
----
-# Introduction
-There are two types of generator plugin:
-- Extension: Web App(Npm Module) = Web App(Npm Module) + Generator Plugin
-- Custom: New Application(Npm Module) = Web App(Npm Module) + Generator Plugin
-In simpler terms, extension means using the original project name of Modern.js, while custom means creating a new name.
-## Identifier
-The type of generator plugin is provided through the `meta` field in `package.json`:
-### Extension
-```json title="package.json"
-{
- "meta": {
-    "extend": "mwa" // module
- }
-}
-```
-### Custom
-```json title="package.json"
-{
- "meta": {
-    "key": "new_app",
-    "name": "new App",
-    "type": "mwa" // module and custom
- }
-}
-```
-:::info
-For custom type, the `type` field supports the `custom` value, which utilizes some best practice templates for project development provided by Modern.js, such as `.gitignore`, `.editorConfig`, etc. Other business-related code templates need to be manually provided through generator plugin.
-:::
-# Creating Initial Project
-### Extension
-```bash
-npx @modern-js/create@latest plugin --plugin @modern-js/generator-plugin-plugin
-? Please select the type of project you want to create: Npm Module
-? Please select the project scenario: Generator Plugin
-? Please fill in the package name of the generator plugin: plugin
-? Please select the programming language: TS
-? Please select the package manager: pnpm
-? Please select the type of plugin: extend
-? Please select the base type of the plugin: Web App
-```
-### Custom
-```bash
-npx @modern-js/create@latest plugin --plugin @modern-js/generator-plugin-plugin
-? Please select the type of project you want to create: Npm Module
-? Please select the project scenario: Generator Plugin
-? Please fill in the package name of the generator plugin: plugin
-? Please select the programming language: TS
-? Please select the package manager: pnpm
-? Please select the type of plugin: custom
-? Please fill in the plugin keyword: new_app
-? Please fill in the display name of the plugin: new App
-? Please select the base type of the plugin: Web App
-```
-## Execution Order
-Generator plugins support using multiple plugins at the same time, which means that multiple `--plugin` parameters are supported when executing `@modern-js/create`.
-### Extension
-For extension generator plugins, when executing with the declared generator plugin parameters, the corresponding lifecycle functions of the project scheme that is extended will be executed in order.
-For example, if there are two generator plugins A and B, both of which extend the Modern.js application scheme. A plugin declares to add the `a.ts` file, and B plugin declares to add the `b.ts` file. When executing `npx @modern-js/create@latest --plugin A --plugin B`, and selecting the Web APP scheme, the default project files of the Web APP will be generated first. Then, the A plugin will create the `a.ts` file, and then the B plugin will generate the `b.ts` file.
-### Custom
-For custom generator plugins, only one plugin can be executed at a time. When declaring the `--plugin` parameter for `@modern-js/create`, a selection option for the scenario of choosing the project scheme will be added after selecting the project scheme, which is the new name defined in the `package.json`. Choosing the corresponding generator plugin for the name will execute the corresponding generator plugin logic after the default project scheme is completed. When declaring the `--plugin` parameter, the corresponding generator plugin names will be listed one by one for selection in the project scheme scenario.

package/docs/en/guides/topic-detail/generator/plugin/context.md DELETED Viewed

@@ -1,104 +0,0 @@
----
-sidebar_position: 4
----
-# Context
-By default, generator plugins will export a function that takes `context` as a parameter. During execution, `context` will be automatically injected into the generator plugin.
-```ts title="src/index.ts"
-import { IPluginContext, ForgedAPI } from '@modern-js/generator-plugin';
-export default function (context: IPluginContext) {
-  context.onForged(async (_api: ForgedAPI, _input: Record<string, unknown>) => {
-    /**
-     * Todo
-     */
-  });
-}
-```
-`context` provides two types of APIs, which are used to customize input and define generator plugin lifecycle logic.
-:::info
-Only some APIs are briefly explained below. For the complete API, please refer to [Generator Plugin API](/guides/topic-detail/generator/plugin/api/context.html).
-:::
-## Customize Input
-Both Modern.js Framework and Modern.js Module have default input interactions. These APIs can be used to add, modify, hide, and provide default values for these inputs.
-For example:
-- Add question
-```ts
-context.addInputBefore('packageManager', {
-  type: 'object',
-  properties: {
-    'username': {
-      type: 'string',
-      title: 'Username',
-    },
-  },
-});
-```
-- Hide question by setting `config`
-```ts
-context.setDefaultConfig({ langauge: 'ts' });
-```
-## Lifecycle
-Generator plugin provide two lifecycle hooks to define generator plugin behavior:
-- `onForged`: Lifecycle after file operations are completed.
-- `afterForged`: Lifecycle after the `onForged` hook function is executed.
-## `onForged`
-Hook function after the Modern.js project scheme generator has completed file operations. It is used to complete file operations in the generator plugin, such as adding template files, overwriting existing files, deleting existing files, etc.
-When multiple generator plugins are executed simultaneously for extension type, the `onForged` operations of the corresponding generator plugins will be executed in order according to the declared order.
-The `onForged` function takes a callback function as a parameter, with `api` and `input` as arguments.
-```ts
-context.onForged(async (api: ForgedAPI, input: Record<string, unknown>) => {
-  const { language } = input;
-  api.addFile({
-      type: FileType.Text,
-      file: `src/index.${language as string}`,
-      templateFile: `index.${language as string}.handlebars`,
-      force: true,
-  });
-})
-```
-The `api` object provides file operation-related methods supported by generator plugin.
-`input` is the current user input, which includes the `--config` parameter definition, the default scheme interaction, and the user input defined by the generator plugin.
-When adding a new file template, define the template file in the `templates` directory, and then operate on it through the `api` method above. The generator plugin defaults to operating on files in the `templates` directory, so there is no need to declare the `templates` path.
-## `afterForged`
-Executed after the `onForged` hook function is completed. It is mainly used to install dependencies, perform git operations, etc.
-By default, Modern.js project scheme will install dependencies and initialize Git after completing file operations, and perform git initial submissions, etc. This hook function can be omitted.
-For custom generator plugins that also support the `custom` type, which only provides a small number of best practice project configurations, installation of dependencies and Git initialization operations need to be completed in this hook function.
-The `afterForged` function also takes a callback function as a parameter, with `api` and `input` as arguments.
-```ts
-  context.afterForged(
-    async (api: AfterForgedAPI, input: Record<string, unknown>) => {
-      const { packageManager } = input;
-      console.info('packageManager:', packageManager);
-      await api.install();
-    },
-  );
-```

package/docs/en/guides/topic-detail/generator/plugin/structure.md DELETED Viewed

@@ -1,106 +0,0 @@
----
-sidebar_position: 1
----
-# Introduction and Project Creation
-## Introduction
-Modern.js provides engineering solutions such as Web App and Npm Module. By using the `@modern-js/create` tool, you can create initial project templates for engineering solutions. The initial project template provides a basic code development environment, simple example code, and configuration, etc.
-The initial templates provided by Modern.js are generic and can meet some common project development needs.
-When you use Modern.js deeply, you will inevitably find that each created project will make some specific similar changes for its own project, such as modifying example code, adding some configurations, enabling certain features, etc.
-Generator plugin can help you to deposit these specific changes for individuals or teams. When running `npx @modern-js/create@latest`, you only need to simply add the `--plugin` parameter to avoid repetitive modification of the project after each project creation.
-Generator plugin is based on the initial template projects provided by Modern.js, providing methods to add, delete, and modify templates, and modifying `package.json`, `modernConfig` configurations, and enabling features through a convenient way.
-## Create Project
-Use `@modern-js/create` to create a generator plugin project directly:
-```bash
-npx @modern-js/create@latest plugin --plugin @modern-js/generator-plugin-plugin
-? Please select the type of project you want to create: Npm Module
-? Please select the project scenario: Generator Plugin
-? Please fill in the package name of the generator plugin: plugin
-? Please select the programming language: TS
-? Please select the package manager: pnpm
-? Please select the type of plugin: extend
-? Please select the base type of the plugin: Web App
-```
-After creating, we can take a look at the directory structure of this project:
-```bash
-.
-├── .changeset
-│   └── config.json
-├── .eslintrc.js
-├── .gitignore
-├── .npmrc
-├── .nvmrc
-├── .prettierrc
-├── README.md
-├── modern.config.ts
-├── package.json
-├── src
-│   ├── modern-app-env.d.ts
-│   └── index.ts
-├── templates
-│   └── .gitkeep
-└── tsconfig.json
-```
-The project is based on the Npm module project, and the core files are as follows:
-```bash
-*
-├── package.json
-├── src
-│   └── index.ts
-├── templates
-│   └── .gitkeep
-```
-## package.json
-In addition to the normal fields of a module project, `package.json` provides a `meta` field to describe information about the generator plugin.
-Generator plugin is divided into two categories: extension and custom. For specific classification definitions, please refer to [Type](/guides/topic-detail/generator/plugin/category).
-```json title="package.json"
-{
-  ...,
-  "meta": {
-    "extend": "mwa"
-  }
-}
-```
-## src/index.ts
-This file is used to complete the content development of the generator plugin.
-```js
-import { IPluginContext, ForgedAPI } from '@modern-js/generator-plugin';
-export default function (context: IPluginContext) {
-  context.onForged(async (_api: ForgedAPI, _input: Record<string, unknown>) => {
-    /**
-     * todo
-     */
-  });
-}
-```
-This file exports a function by default, and the function takes `context` as a parameter. The `context` object provides API methods supported by the generator plugin, which can be used to implement the logic of the generator plugin. The capabilities provided by `context` can be found in [context](/guides/topic-detail/generator/plugin/context).
-## templates
-The `templates` directory contains template files for the current customization method, supporting [Handlebars](https://handlebarsjs.com/) and [EJS](https://ejs.co/) formats. Different rendering engines will be used for rendering according to the template file suffix. If there is no suffix, the template file will be copied directly to the target directory.
-If the template file is a `js`, `ts`, or `json` file, it is recommended to use the `.handlebars` or `.ejs` suffix directly to avoid project eslint errors and recognition issues in Monorepo projects.
-The `.gitignore` and `.npmrc` files in the template will be automatically deleted when publishing the npm package, so it is necessary to use the `.handlebars` or `.ejs` suffix to keep them.

package/docs/en/guides/topic-detail/generator/plugin/use.md DELETED Viewed

@@ -1,33 +0,0 @@
----
-sidebar_position: 3
----
-# Usage
-`@modern-js/create` provides the `--plugin` parameter to run the generator plugin project.
-`--plugin` supports three formats:
-## Absolute path
-Suitable for local development and debugging. After development is completed, build the project by running `npm run build` in the generator plugin project, and then use the following command for testing:
-```bash
-npx @modern-js/create@latest --plugin <pluginPath>
-```
-## Relative path
-Suitable for local development and debugging or when the generator plugin project and the target project to be created are in the same Monorepo and there is no need to publish an NPM package. After building the generator plugin project, use the following command:
-```bash
-npx @modern-js/create@latest --plugin file:../<pluginPath>
-```
-## NPM package
-Suitable for scenarios where the generator project is published on npm for sharing.
-```bash
-npx @modern-js/create@latest --plugin <pluginPackage>
-```

package/docs/zh/guides/topic-detail/generator/_meta.json DELETED Viewed

@@ -1,17 +0,0 @@
-[
-  {
-    "type": "dir",
-    "name": "create",
-    "label": "@modern-js/create"
-  },
-  {
-    "type": "dir",
-    "name": "new",
-    "label": "new-command"
-  },
-  {
-    "type": "dir",
-    "name": "plugin",
-    "label": "generator-plugin"
-  }
-]

package/docs/zh/guides/topic-detail/generator/create/_meta.json DELETED Viewed

	@@ -1 +0,0 @@
1	- ["use", "option", "config"]