I. Overview

@oinone/cli (command: oinone-frontend) is the Oinone frontend project scaffold for quickly generating pnpm workspace-based Oinone frontend projects. Current CLI version: 7.2.7, supported Oinone framework versions: 7.2.x (latest 7.2.9) / 6.4.x (latest 6.4.12).

Features:

• Interactive project creation with sensible defaults and validation
• Silent mode for CI/CD pipelines
• Optional enterprise repository credential generation
• Built-in cache command for static resource cache management
• Built-in doctor command for environment checks

II. Environment Requirements

Phase	Requirement
Run CLI	Node.js
Install generated frontend project dependencies	pnpm recommended

Note

If pnpm and related tools are not yet installed, use the following command (version pinning is recommended to avoid instability caused by newer versions):

npm install -g pnpm@^9 lerna@9.0.3 rimraf@6.1.2

Tip

Before creating a project, please complete the global configuration described in Appendix 2: Frontend Environment Configuration (Node.js v22.13.0, pnpm@^9, etc.) to avoid unexpected errors when installing dependencies or starting the project.

III. Installation

npm install -g @oinone/cli

Verify installation:

oinone-frontend --version

You can also use npx without global installation:

npx @oinone/cli create my-project

IV. Creating a Project

(I) Interactive Creation

Run the create command and follow the prompts:

oinone-frontend create

(II) Silent Creation (Recommended for CI/CD)

Pass all configurations via parameters without interaction:

Community edition:

oinone-frontend create my-project \
  --oinone-version 7.2.0 \
  --edition community

Enterprise edition:

oinone-frontend create my-project-enterprise \
  --oinone-version 7.2.0 \
  --edition enterprise

(III) Using --company-name / --project-name

oinone-frontend create \
  --company-name ss \
  --project-name oms \
  --oinone-version 7.2.0 \
  --edition community

Note

When both --company-name and --project-name are specified, the generated directory name is {company}-{project}-frontend (e.g. ss-oms-frontend in the example above).

(IV) Static Resource Download

The --download-static-resource parameter controls whether to download static resources (icons, images, etc.):

oinone-frontend create my-project \
  --oinone-version 7.2.0 \
  --edition community \
  --download-static-resource true

(V) Dry-Run Mode

Use --dry-run to validate parameters without writing to disk:

oinone-frontend create my-project \
  --oinone-version 7.2.0 \
  --edition community \
  --dry-run

(VI) Creating an Oinone 6.4.* Project

oinone-frontend create my-project-64 \
  --oinone-version 6.4.0 \
  --edition community

V. Package Naming and Project Structure

The generated frontend project is a pnpm workspace-managed monorepo. Template packages are renamed based on CLI parameters:

Template Package	Generated Package
ss-boot	{company}-boot
ss-oinone	{company}-oinone
ss-admin-widget	{company}-admin-widget
ss-project	{company}-project

Note

Not only are package directory names replaced — the ss- prefix and @ss/ scope in source code are also replaced accordingly (e.g. @ss/ → @{company}/).

Generated project directory structure:

my-project/
├── pnpm-workspace.yaml       # pnpm workspace configuration
├── package.json               # Root package.json
├── lerna.json                 # Lerna configuration
├── .npmrc                     # npm registry configuration
├── eslint.config.ts           # ESLint configuration
└── packages/
    ├── ss-boot/               # Assembly layer (app entry, Vue + Vite)
    │   └── src/
    │       └── main.ts        # App entry file
    ├── ss-oinone/             # Oinone integration layer
    ├── ss-admin-widget/       # No-code platform widgets
    └── ss-project/            # Business customization layer

Note

The above is the structure generated by oinone-frontend create my-project. When using interactive mode or the --company-name / --project-name parameters, the directory name is {company}-{project}-frontend (e.g. ss-oms-frontend).

VI. Starting the Project

After generating the project, run the following commands to install dependencies and start the development server:

cd my-project
pnpm install
pnpm run dev

Note

• Open the URL printed in the terminal to view the application.
• The project's built-in .npmrc is preconfigured with the npmmirror registry to speed up dependency installation.

VII. Command Reference

(I) Global Parameters

Parameter	Description
-l, --lang <lang>	Language (zh-CN / en-US)
-v, --version	Output version number
-h, --help	Output help

(II) oinone-frontend create [projectName]

Parameter	Description
--company-name <name>	Silent mode: company/organization name
--project-name <name>	Silent mode: project name; when used with --company-name, directory is {company}-{project}-frontend
--download-static-resource <boolean>	Whether to download static resources (true / false)
-o, --oinone-version <version>	Oinone version (only 7.2.0 / 6.4.0 are supported)
-e, --edition <edition>	Edition type: community / enterprise
-f, --force	Overwrite/merge if target directory exists
-d, --dry-run	Dry-run mode: do not write to disk

(III) oinone-frontend doctor

Parameter	Description
-o, --oinone-version <version>	Oinone version to validate (only 6.4.* and 7.2+ are supported)

oinone-frontend doctor --oinone-version 7.2.0

(IV) oinone-frontend cache

Command	Description
cache info	Print cache directory information (including cached files and sizes)
cache clean	Clear cached static resources

# View cache info
oinone-frontend cache info

# Clear static resource cache
oinone-frontend cache clean

Tip

Uninstalling the CLI does not automatically remove the static resource cache from the system temp directory. To clean it up, run oinone-frontend cache clean before uninstalling.

VIII. Version and Template Mapping

Oinone Version	Template Directory	Description
6.4.*	template-6.4.0	Oinone 6.4 frontend project
7.2+	template-7.2.0	Oinone 7.2 frontend project

Release notes:

• Oinone 7.2.x Release Notes
• Oinone 6.4.x Release Notes

Warning

Unsupported Oinone versions will result in an immediate error and no project will be generated.

IX. Source Dependency (Local Development)

When you need to debug or extend the Oinone frontend framework (oinone-kunlun) source code, you can link the generated project with the framework source for local development as follows.

(I) How It Works

pnpm workspace maps local packages under packages/ to node_modules via symlinks. By placing the oinone-kunlun source in the packages/ directory and registering its sub-packages as workspace members, @oinone/kunlun-* dependencies resolve to the local source, with changes taking effect immediately.

(II) Steps

1. Clone the oinone-kunlun Framework Source

Clone the framework source into the project's packages/ directory and switch to the corresponding branch:

cd my-project/packages
git clone https://github.com/oinone/oinone-kunlun.git
cd oinone-kunlun
git checkout feat/7.2.0    # 7.2 template uses this branch; choose the matching branch for 6.4

2. Update pnpm-workspace.yaml

Edit the project root pnpm-workspace.yaml to include all oinone-kunlun sub-packages:

packages:
  - 'packages/**'

3. Check .npmrc Configuration

Ensure the project root .npmrc contains the following parameters, which are essential for pnpm to resolve local workspace dependencies:

link-workspace-packages=true
prefer-workspace-packages=true

4. Install Dependencies

Return to the project root and reinstall dependencies to establish local links:

cd ../..
pnpm install

5. Resolve Missing CSS Artifacts

The dependencies.ts files in oinone-kunlun import CSS files that are only generated after building. These files do not exist in a local development setup and will cause startup errors. Simply comment out the corresponding CSS imports:

File 1: packages/oinone-kunlun/packages/kunlun-vue/packages/dependencies/src/dependencies.ts

// These CSS artifacts are not yet built in local dev; comment them out:
// import '@oinone/kunlun-vue-ui-common/dist/oinone-kunlun-vue-ui-common.css';
// import '@oinone/kunlun-vue-ui/dist/oinone-kunlun-vue-ui.css';
// import '@oinone/kunlun-vue-admin-layout/dist/oinone-kunlun-vue-admin-layout.css';
// import '@oinone/kunlun-vue-admin-base/dist/oinone-kunlun-vue-admin-base.css';
// import '@oinone/kunlun-vue-expression/dist/oinone-kunlun-vue-expression.css';

File 2: packages/oinone-kunlun/packages/kunlun-mobile-vue/packages/mobile-dependencies/src/dependencies.ts

// These CSS artifacts are not yet built in local dev; comment them out:
// import '@oinone/kunlun-vue-ui-common/dist/oinone-kunlun-vue-ui-common.css';
// import '@oinone/kunlun-vue-mobile-base/dist/oinone-kunlun-vue-mobile-base.css';

Note

• To restore the CSS imports later, run git checkout -- <file>.

6. Start the Development Server

Return to the project root and start:

pnpm run dev

Any changes to source files under packages/oinone-kunlun/ will take effect immediately and can be verified in the browser.

Tip

• To revert source changes, use git checkout -- <file>.
• If you modify the workspace configuration or add/remove dependency packages, re-run pnpm install to update links.
• Building oinone-kunlun locally is time-consuming and may introduce instability due to environment differences. Source dependency is only recommended for breakpoint debugging — for project builds, use the pre-built @oinone/kunlun-* packages from the remote registry.