Command Line Tool

A command line tool (CLI) is a way of interacting with a program through text commands in a terminal. Qingkuai provides an official command line tool @qingkuai/cli. After installation it is invoked through the qingkuai command, and its capabilities are as follows:

• init: initialize a new Qingkuai project in the working directory, with JavaScript and TypeScript templates

• dev: start the dev server with instant hot module replacement (HMR)

• build: build the whole application or a component library into distributable output

• preview: start the preview server to preview the build output locally

• check: run syntax checks on component files and TypeScript files, with optional type checking

• format: format component files and other files supported by Prettier

• build-types: generate .d.ts declaration files for components and TypeScript files, used to expose types for library output

Installation

Install the CLI globally with a package manager:

➜ npm install -g @qingkuai/cli

➜ pnpm add -g @qingkuai/cli

➜ yarn global add @qingkuai/cli

After installation, you can verify it by checking the version number:

➜ qingkuai -v

Output similar to the following means the installation succeeded:

Version 1.0.0

When you are unsure how a command works, add the --help (-h) option to any command to view its help:

init

Create a new Qingkuai application in the working directory:

➜ qingkuai init qingkuai-app

To initialize in an existing directory, pass .:

➜ qingkuai init .

The available options for this command:

dev

Start the vite-based dev server with instant hot module replacement:

➜ qingkuai dev --port 5173 --open

The server's behavior can be adjusted with the following options:

build

Build the application or a component library into distributable output; running it directly builds the whole application with index.html as the entry:

➜ qingkuai build

Passing a component file as a positional argument enters library mode, where --format sets the output format and --name sets the global variable name for the umd and iife formats, falling back to the name field in package.json:

➜ qingkuai build src/components/Button.qk --format es,cjs,umd
➜ qingkuai build src/components/Button.qk --format iife --name MyButton

The build behavior can be adjusted with the following options:

preview

Preview the output of build locally through vite's preview server; the build must be completed first, and an error is reported when the output directory does not exist:

➜ qingkuai build && qingkuai preview --open

The preview server's behavior can be adjusted with the following options:

check

Run syntax checks on Qingkuai component files and TypeScript files:

➜ qingkuai check src

Adding the --types option additionally runs type checking:

➜ qingkuai check --types src

Positional arguments accept one or more files or directories, and the process exits with a non-zero code when errors exist:

➜ qingkuai check --types src/components/Button.qk src/utils/*

The available options for this command:

format

Based on Prettier and prettier-plugin-qingkuai, formats component files and other files supported by Prettier, printing the result to standard output by default:

➜ qingkuai format src

Add --write to write the result back to the files:

➜ qingkuai format src --write

Add --check to only check whether there are files waiting to be formatted:

➜ qingkuai format src --check

CLI flags take priority over the configuration file; the available options for this command:

build-types

Generate the corresponding .d.ts declaration files for TypeScript and Qingkuai component files, used to expose types when building library output:

➜ qingkuai build-types src --out dist/types

The available options for this command:

Using Upstream Tools

Since the project's dependencies do not directly include Vite or Prettier, the CLI package re-exports the type definitions and methods of these upstream tools; when writing configuration files, import them from the CLI package instead of adding them as project dependencies — this avoids version conflicts and automatically picks up upstream tool updates when the CLI is upgraded:

// vite.config.ts
import { defineConfig } from "@qingkuai/cli/vite"

export default defineConfig({
    server: {
        port: 3000
    }
})

// prettier.config.ts
import type { Config } from "@qingkuai/cli/prettier"

const config: Config = {
    printWidth: 100,
    singleQuote: true,
    spaceAroundInterpolation: true
}

export default config

The re-exported TypeScript is usually not aimed at configuration files but at build scripts and similar scenarios. For example, the following script resolves all source files covered by tsconfig.json and can serve as the foundation of a custom build pipeline:

// scripts/list-files.mjs
import ts from "@qingkuai/cli/typescript"

const configFile = ts.readConfigFile("tsconfig.json", ts.sys.readFile)
const parsed = ts.parseJsonConfigFileContent(
    configFile.config,
    ts.sys,
    process.cwd()
)

// Print all source files covered by the tsconfig
console.log(parsed.fileNames)

Edit this page on github (This page has been translated from the Chinese version of the site. There may be inaccuracies in the translation. We welcome your help to improve the accuracy of this document.)