Command Reference

Global: rspfx --version, rspfx --help.

All commands read config/config.json, config/package-solution.json, src/*/*.manifest.json. If a bundler config (vite.config.ts, rsbuild.config.ts, rspack.config.ts) exists it is loaded via jiti and the plugin marker is used; otherwise the CLI synthesizes it from manifests. Flags override file options.

Pick bundler at scaffold/migrate: --bundler vite (default), rsbuild, or rspack.

You don't need @microsoft/sp-* for most web parts — they are externalized.

rspfx new <name>

Create a project and initialize git (no dependency install — run your package manager manually). Convenience wrapper — recommended path is bring-your-own scaffold (npm create vite@latest / pnpm create vite@latest / yarn create vite@latest / bun create vite@latest / deno run -A npm:create-vite@latest + add @mbsks/rspfx-plugin).

Flag	Values
--component <type>	webpart (default), applicationcustomizer, fieldcustomizer, listviewcommandset, formcustomizer, library
--framework <id>	vanilla, react, solid, preact, vue, svelte (web parts)
--bundler <id>	vite (default), rsbuild, rspack
--language <lang>	ts, js (web parts)
--spfx-version <v>	See compatibility.md#spfx-version-matrix and Release 1.23
--pm <pm>	pnpm, npm, yarn, bun, deno
--no-install	Kept for compatibility; install never runs automatically
--yes	Accept defaults, no prompts

rspfx new my-app --framework vue --yes
rspfx new my-extension --component applicationcustomizer --yes

Prefer npm create vite@latest my-app -- --template react-ts (or pnpm create vite@latest / yarn create vite@latest / bun create vite@latest / deno run -A npm:create-vite@latest, better-t-stack, TanStack Router, etc.) then npm i -D @mbsks/rspfx-plugin @mbsks/rspfx-cli (or pnpm add -D / yarn add -D / bun add -D / deno add -D) and add rspfxVite() to vite.config.ts — see getting-started.md#2-create-a-project. rspfx new does the same but hides the starter choice. No codebase changes needed for other starters — packages/plugin/src/vite.ts/rsbuild.ts/rspack.ts already support Vite/Rsbuild/Rspack.

rspfx migrate

Migrate Heft/Gulp project. Only command that edits files.

Flag	Values
--to <version>	0.1 (default)
--dry-run	Preview without writing
--bundler <id>	vite (default), rsbuild, rspack
--revert	Restore from .rspfx/migrate-backup.json

rspfx migrate --dry-run
rspfx migrate --bundler rspack
rspfx migrate --revert

Edits package.json (drops Heft/webpack/gulp, adds rspfx scripts), rewrites config/config.json lib → src, rewrites pkg: SCSS imports, deletes Heft-only files, writes bundler config + plain tsconfig.json, backs up to .rspfx/migrate-backup.json. Commit before migrating.

rspfx dev:vite / rspfx vite:dev

Fastest way to try dev mode in any SPFx project.

Auto-detects Node/SPFx version/framework/tsconfig.json, adds lean dev plugin, creates vite.config.ts, then starts Vite on :4321.

See guide/dev-vite.md.

Flag	Values
--dry-run	Preview plan without writing files or starting Vite
--force	Overwrite existing vite.config.*
--tsconfig <path>	Explicit tsconfig path (relative or absolute, else auto-detect tsconfig.json / tsconfig.build.json / tsconfig.app.json / tsconfig*.json)
--refresh	Fast refresh (state-preserving where supported)
--browser	Open browser (off by default)
--port <n>	Override dev.port (default 4321)
--mode <local|sharepoint>	local (default) or sharepoint when tenant set
--tenant <url>	Tenant URL (else dev.tenantUrl or SPFX_SERVE_TENANT_DOMAIN)

What it does (apps/cli/src/commands/dev-vite.ts:195 runDevVite):

Checks Node >=20 (Vite 8 needs >=20.19 per compatibility.md#vite-node-matrix), detects spfxVersion from package.json @microsoft/sp-core-library (supports legacy 1.11–1.19 dev-only via registerSpfxVersion), detects framework from dependencies, finds tsconfig.json (default) or custom via --tsconfig and links as build.tsconfigPath, sets package.json type: module + devDependencies.@mbsks/rspfx-plugin-dev + vite + script dev:vite, generates vite.config.ts with rspfxViteDev (if no vite.config.*/rsbuild.config.*/rspack.config.* per apps/cli/src/config.ts:25), handles rush-stack-compiler base.json stub + esbuild.tsconfigRaw, then spawns Vite via apps/cli/src/vite.ts:1 spawnViteDev (VITE_CONFIG_NATIVE_IGNORE_WARNING=true).

rspfx dev:vite --dry-run                              # preview
rspfx dev:vite                                        # scaffold + run
rspfx dev:vite --tsconfig tsconfig.app.json --force   # custom tsconfig
rspfx dev:vite --tenant https://contoso.sharepoint.com --mode sharepoint --browser
npm run dev:vite   # after scaffold, runs `vite`

Keeps gulp serve/heft build for production.

Delete vite.config.ts to revert.

Production build/package stay on official toolchain until rspfx migrate.

rspfx dev

Dev server on :4321 — optional CLI alternative. Primary for Vite users is vite dev --port 4321 with rspfxViteDev() / rspfxVite() (Vite handles HMR/serve, the plugin adds /temp/manifests.js, reload, and workbench URL via configureServer); rspfx dev uses the same dev-runtime.

Flag	Values
--refresh	Fast refresh (state-preserving where supported)
--browser	Open browser (off by default)
--port <n>	Override dev.port (default 4321)
--mode <local|sharepoint>	local (default) or sharepoint when tenant set
--tenant <url>	Tenant URL (else dev.tenantUrl or SPFX_SERVE_TENANT_DOMAIN)

Local (default, no tenant): http://localhost:4321/ — preview at / + mock /_api, HTTP, no cert. Supports ?locale=fr-fr and local/data.json seeding.

SharePoint (tenant set): https://localhost:4321 — /temp/manifests.js, /dist/*.js. Workbench URL printed: https://<tenant>/_layouts/15/workbench.aspx?debug=true&noredir=true&debugManifestsFile=<encoded https://localhost:4321/temp/manifests.js>.

Cert is auto-generated in ~/.rspfx/certs (825-day self-signed) and vite dev / rspfx dev warn if missing/expiring/untrusted; rspfx doctor verifies. See getting-started.md#cert-trust.

Reload via /__rspfx_hot.json poll → location.reload().

vite dev --port 4321            # primary
vite dev --port 4321 -- --refresh
rspfx dev                       # optional alternative, same runtime
rspfx dev --refresh
rspfx dev --mode sharepoint --tenant https://contoso.sharepoint.com --browser

Tip: :4321 is HTTP in local preview, HTTPS in SharePoint mode. If the workbench shows blank or CORS errors, run rspfx doctor and trust the cert per the printed instructions.

For the easiest existing-project try without manual vite.config.ts, use rspfx dev:vite above.

rspfx build

Compile to dist/ + release/ — required; vite build alone does not generate manifests.js/release.

Flag	Values
--no-minify	Disable minify
--sourcemap	Emit hidden source maps

Bundler config optional — without it the CLI synthesizes and runs the bundler directly.

rspfx build --no-minify --sourcemap

rspfx package

Build + assemble sharepoint/solution/<name>.sppkg (from paths.zippedPackage) — required; vite build alone does not generate .sppkg.

Flag	Values
--no-build	Use existing release/

Auto-includes teams/ and sharepoint/Resources*.resx when present.

rspfx package --no-build

rspfx deploy

Package + upload to app catalog. Needs RSPFX_ACCESS_TOKEN + RSPFX_APP_CATALOG_URL. Without token prints manual steps. Validates URL, 120 s timeout.

RSPFX_ACCESS_TOKEN=<token> RSPFX_APP_CATALOG_URL=https://contoso.sharepoint.com/sites/appcatalog rspfx deploy

rspfx analyze

Build + console table + .rspfx/analyze.html. Module counts work for all bundlers (Vite/Rsbuild via .rspfx/stats.json).

rspfx doctor

Checks Node 20+, manifests, framework, sp-* externals, bundles, port, outDir, cert (exists / valid >7d / key.pem 0600 / trusted).

Flag	Values
--fix	Fix missing configs/certs then re-validate

Exit 1 on fail — use in CI.

rspfx doctor --fix

rspfx clean

Removes dist/, release/, temp/, .rspfx, node_modules/.cache, sharepoint/solution. Refuses outside a project.

Bundler plugin

RSPFx is a plugin for any Vite/Rsbuild/Rspack starter — scaffold with npm create vite@latest (or pnpm create vite@latest / yarn create vite@latest / bun create vite@latest / deno run -A npm:create-vite@latest), better-t-stack, TanStack Router, create-rsbuild, etc., then add the plugin. Config file is optional (CLI synthesizes from manifests if missing).

Vite vite.config.ts — recommended default:

import { defineConfig } from 'vite';
import { rspfxVite } from '@mbsks/rspfx-plugin';
export default defineConfig({ plugins: [rspfxVite({ name: 'my-app', framework: 'react', spfxVersion: '1.23' })] });

Rsbuild rsbuild.config.ts:

import { defineConfig } from '@rsbuild/core';
import { rspfxRsbuild } from '@mbsks/rspfx-plugin';
export default defineConfig({ plugins: [rspfxRsbuild({ name: 'my-app', framework: 'react' })] });

Rspack rspack.config.ts:

import { RspfxPlugin, rspfxResolve } from '@mbsks/rspfx-plugin';
export default { resolve: rspfxResolve(), plugins: [new RspfxPlugin({ name: 'my-app', framework: 'react' })] };

For all three, rspfx build gives the same output as native vite build / rspack build / rsbuild build. No codebase changes needed for new starters — packages/plugin/src/vite.ts, packages/plugin/src/rsbuild.ts, packages/plugin/src/rspack.ts already cover Vite/Rsbuild/Rspack; routers (TanStack Router etc.) are just dependencies inside the Vite project.

Options

Group	Keys
Identity	name, version, spfxVersion, framework
Dev	dev.port (4321), dev.https (true), dev.hostname (localhost), dev.tenantUrl, dev.openBrowser (false), dev.fastRefresh, dev.workbench/initialPage
Build	build.outDir (dist), build.releaseDir (release), build.sourcemap/minify/splitChunks (deprecated — use bundler options; splitChunks must stay false)
Layout	paths.srcDir, paths.webpartsDir, paths.extensionsDir, paths.librariesDir, paths.configDir
Deploy	deploy.appCatalogSiteUrl

Environment variables

Single home for operator env vars. No other RSPFX_* vars are implemented.

Variable	Use
RSPFX_LOG_LEVEL	error | warn | info | debug | trace
RSPFX_LOG_JSON	1 → JSON lines
SPFX_SERVE_TENANT_DOMAIN	Fallback for dev.tenantUrl
RSPFX_ACCESS_TOKEN + RSPFX_APP_CATALOG_URL	Token + URL for rspfx deploy
RSPFX_NPM_OTP	OTP for node scripts/publish.mjs