The @spfxappdev/cli is a command-line interface (CLI) tool that helps you to initialize and develop your SPFx (SharePoint Framework) applications.
It assists in multiple ways, including creating a new project with your preferred package manager, initializing your preferred settings after creating the project and scaffolding services or models.
For example, if you run the spfxappdev new
command, the yo @microsoft/sharepoint
command is automatically invoked and your configured package manager is passed as option.
If the project is already created, you can run the spfxappdev init
command. This command will register some gulp
tasks or modify your SharePoint Framework solution to use alias
paths instead of relative paths.
You can configure the CLI the way you need it. A kind of "my own SPFx generator for each project". Not everything is configurable yet, but the CLi will be further developed. And yes, I have to admit the rules and settings match my typical settings and configurations. But since I didn't want to keep doing the same steps for every project, I decided to develop this CLI to make my life easier. Maybe you like my CLI too. I am also open for improvement suggestions. Read more about my tips on how to configure an SPFx project after it is created. This CLI is based on or modifies the project as described here
- Installation
- Basics
- CLI command reference
- How to use custom templates
- How to use the alias paths
- How to register more aliases
- Further links
With
npm
, you have several options to control how your operating system's command line resolves the location of thespfxappdev
CLI binary. Here I describe the global installation of thespfxappdev
binary using the-g
option. This option provides some level of convenience and is the approach I use throughout the documentation. Note that when installing any npm package globally, it is the user's responsibility to ensure that the correct version is installed. This also means that if you have different projects, each will run the same version of the CLI.
Install the CLI globally using the npm install -g command (see the Note above for details about global installs).
npm i @spfxappdev/cli -g
Once installed, you can invoke CLI commands directly from your OS command line through the spfxappdev
executable. See the available CLI commands by entering the following:
spfxappdev --help
Note: You can also use the alias
spfx
instead ofspfxappdev
.
You can get help on a single command by using the following construct. Substitute any command, such as new
, init
, etc., where init
appears in the example below to get detailed help on that command:
spfxappdev init --help
Creates a new spfx project by running the yo @microsoft/sharepoint
command. You can pass all options that yo @microsoft/sharepoint
supports (you can get all available options by running yo @microsoft/sharepoint --help
).
spfxappdev new [options]
spfx n [options]
If no package manager is specified (via the --package-manager
option), the package manager from your configuration is passed to the new
command. (See config command for more details)
NOTE: When
pnpm
is used as package manager, the commandspnpm config set auto-install-peers true --location project
andpnpm config set shamefully-hoist true --location project
are executed. For more information, read this post
spfxappdev new
spfx n --framework react --skip-install --component-type "webpart" --component-name hello-spfx-cli
Generates and/or modifies files based on the specified type.
spfxappdev generate <type> <name>
spfx g <type> <name>
Creates a new component with the specified <name>
to the current project.
- Creates a folder for the specified
<type>
. For exampleservices
ormodels
- Creates the specified
<type>
with the specified<name>
. For example, theService
with the nameNews
becomesNewsService
. - Creates an
index.ts
in the<type>
specific folder and exports the newly created class(es)
spfxappdev generate service News
spfx g s News
Argument | Description |
---|---|
<type> |
The (component) type to generate. See the table below for the available types. |
<name> |
The name of the generated component. |
Name | Alias | Description |
---|---|---|
service |
s |
Create a new service that can be consumed with the serviceScope . |
model |
m |
Create a new and empty model interface and class. |
You can create a model based on a SharePoint list (fields). The only options required are --list
OR --listName
to tell the CLI that you want a model based on that specific list.
Option | Alias | Description |
---|---|---|
--list |
-l |
SharePoint web relative list URL e.g. Lists/MyList or SitePages . |
--listName |
-ln |
The Name/Title of the List |
--weburl |
-u |
OPTIONAL: You can specify an absolute web URL where the list is located. If this option is not set, the local or global settings will be used (property: siteurl ). If the siteurl value from the configuration file is empty, the CLI will automatically ask for the web URL |
--username |
-user |
OPTIONAL: You can specify a login name for the user to authenticate to Sharepoint. If this option is not set, the local or global settings are used (property: username ). If the username value from the configuration file is empty, the CLI will automatically prompt for the username |
--password |
-p |
OPTIONAL: You can specify a password for the user to authenticate to Sharepoint. If this option is not set, the local or global settings are used (property: password ). If the password value from the configuration file is empty, the CLI will automatically prompt for the password |
--hidden or --no-hidden |
Normally, the model is created with fields that are not "hidden". However, you can specify whether you want to include the hidden fields as well |
Note: The SharePoint list based model generator needs the npm package
@spfxappdev/mapper
to map the internal field names to the (friendly) model properties.
Initializes/configures the project.
After you run the command, the following steps are taken:
- A new folder
@spfxappdev
is created in the root directory of the project - The
gulpfile.js
file is modified: Aliases are registered, thebump-version
task is defined and the possibility to build your solution in such a way that a warning will not cause the build process to fail. tsconfig.json
is changed: Pathaliases
andbaseUrl
are set.fast-serve/webpack.extend.js
is changed (if available): Aliases are registered- The
package.json
file is modified: Thepublish
andpublish:nowarn
commands are defined - If a
siteurl
is set in the config file, then theconfig/serve.json
is updated and the{tenantDomain}
placeholder is replaced with the value from the config ()
- If you have defined additional
npm
packages and the--no-install
option is not passed, then all defined packages will be installed (See configuration section)
spfxappdev init [options]
spfx init [options]
Option | Alias | Description |
---|---|---|
--package-manager |
-pm |
If additional packages are to be installed (specified in config), the package manager can be specified here (npm , pnpm or yarn ). Otherwise the package manager from the config (default npm ) is used |
--install or --no-install |
- | The specified npmPackages from the configuration file should (not) be installed (default: true ) |
After running the spfxappdev init
command, you can use the "aliases" instead of relative paths (see "How to use the alias paths" section).
Also, you can run the npm run publish
command. This command runs gulp clean
, gulp build
, gulp bundle --ship
and gulp package-solution --ship
. The newly registered gulp task bump-version
is also executed and increases automatically the version of the solution.
Normally, a warning in the terminal causes the build to fail. If you want to suppress the warnings for the build, you can run the
npm run publish:nowarn
command.
If you want to increase the version without creating or bundling the solution, you can use this command:
gulp bump-version
More information about the
publish
andbump-version
command can be found in my blog post
Renames the default .eslintrc.js
and tsconfig.json
files and creates new files that inherit from the original files. This allows you to define your own ESLint rules. By default, the command defines custom rules that come with the CLI. But you can override the templates with the config
command (See section "How to use custom templates")
spfxappdev custom-rules
spfx rules
The original .eslintrc.js
and tsconfig.json
are renamed to ms-eslint.js
and ms-tsconfig.json
. The new rules extend the original rules, but now you can overwrite the rules or define new ones. The files become smaller and the original files stay untouched.
Gets or sets your personal settings (configurations).
You can configure the CLI according to your personal preferences using its settings. The settings are stored on the disk in the current user's folder: C:\Users/{user}\.config\configstore\@spfxappdev\cli.json
on Windows and /Users/{user}/.config/configstore/@spfxappdev\cli.json
on macOS. The configuration file is created when you use the cli for the first time.
To reset settings to their default values, remove them from the configuration file or remove the whole configuration file.
spfxappdev config
spfx c
From version
1.1.0
there is the possibility to create a "local" configuration file. If one exists, the settings from the local file will take effect. If one or more properties do not exist in the local file, the values from the global configuration file are used.
Displays all settings
spfxappdev config all
spfx c all
Option | Alias | Description |
---|---|---|
--local |
-l |
If specified, the local configuration file is used. |
Shows the value of the specified <key>
spfxappdev config get <key>
spfx c get <key>
Option | Alias | Description |
---|---|---|
--local |
-l |
If specified, the local configuration file is used. |
Sets the specified <value>
for the specified <key>
spfxappdev config set <key> <value>
spfx c set <key> <value>
Only templatesPath
, packageManager
, siteurl
, username
and password
properties can be set via spfxappdev config set
command. For the settings key npmPackages
you should use the command spfxappdev config add <key> <values...>
.
Option | Alias | Description |
---|---|---|
--local |
-l |
If specified, the local configuration file is used. |
spfxappdev config set templatesPath "D:\mySPFxCLITemplates"
Now you can use your own templates for .eslintrc.js
and tsconfig.json
. Just create the files eslint.js.txt
and tsconfig.txt
. Open the files and paste the contents of here and here and set your own rules.
Adds the specified value(s) for the specified <key>
. This command is available only for <key>
which stores a "list" of values. The existing values are not removed. The new values will be added to the list (at the end).
spfxappdev config add <key> <values...>
spfx c add <key> <values...>
Note: Currently only the
<key>
"npmPackages
" is supported
Option | Alias | Description |
---|---|---|
--local |
-l |
If specified, the local configuration file is used. |
#Adding multiple values at the same time
spfxappdev config add npmPackages @spfxappdev/utility @pnp/sp
#Adding multiple values at the same time
spfxappdev config add npmPackages @spfxappdev/mapper
Removes the specified value(s) for the specified <key>
. This command is available only for <key>
which stores a "list" of values.
spfxappdev config remove <key> <values...>
spfx c remove <key> <values...>
Note: Currently only the
<key>
"npmPackages
" is supported
Option | Alias | Description |
---|---|---|
--local |
-l |
If specified, the local configuration file is used. |
#Removing multiple values at the same time
spfxappdev config remove npmPackages @spfxappdev/utility @pnp/sp
#Removing multiple values at the same time
spfxappdev config remove npmPackages @spfxappdev/mapper
Removes all values for the specified <key>
. This command is available only for <key>
which stores a "list" of values.
spfxappdev config remove-all <key>
spfx c ra <key>
Note: Currently only the
<key>
"npmPackages
" is supported
Option | Alias | Description |
---|---|---|
--local |
-l |
If specified, the local configuration file is used. |
spfxappdev config remove-all npmPackages
This command clears the list and creates an empty array
[]
.
Creates a new local configuration file based on the global file, but without the SharePoint password.
spfxappdev config create
spfx c create
Currently, the CLI only supports custom templates for the .eslintrc.js
and tsconfig.json
files. If you want to override the CLI default templates, you can set your own templatesPath
value using the command:
spfxappdev config set templatesPath "{YourTemplatesFolderPath}"
Make sure that you have created the files named eslint.js.txt
and tsconfig.txt
in the folder. If one of these files does not exist, the default CLI templates will be used (only for the non-existing file). You can copy the original files from the @spfxappdev/cli
npm package ({pathtoyourglobalNPMFolder}\@spfxappdev\cli\lib\templates\create
). Or you can paste the contents of here and here. Then you can change the templates as you like.
Most use relative paths to refer to files from the solution. Here are a few examples
import HelloWorldWebPartComponent from './components/HelloWorldWebPartComponent';
import { MyComponent } from '../../components/MyComponent';
But this is not so nice and if you want to change the structure or reuse the code, you need to update these paths.
For this reason you can use alias
instead.
Same example as above, but with alias
import HelloWorldWebPartComponent from ' @webparts/helloworld/components/HelloWorldWebPartComponent';
import { MyComponent } from '@components/MyComponent';
If you run spfxappdev init
the following aliases are registered:
"@webparts": "src/webparts",
"@components": "src/components",
"@src": "src",
If you want to register more aliases, you need to change some files (all of the following mentioned)
Open the newly created @spfxappdev/customAlias.js
file and register additional aliases (starting from line 11)
generatedConfiguration.resolve.alias['@apps'] = path.resolve(__dirname, '..', 'lib/extensions');
NOTE: In this file, you should use the
lib
folder instead ofsrc
.
function resolveCustomAlias(build) {
build.configureWebpack.mergeConfig({
additionalConfiguration: (generatedConfiguration) => {
if (!generatedConfiguration.resolve.alias) {
generatedConfiguration.resolve.alias = {};
}
generatedConfiguration.resolve.alias['@webparts'] = path.resolve(__dirname, '..', 'lib/webparts');
generatedConfiguration.resolve.alias['@components'] = path.resolve(__dirname, '..', 'lib/components');
generatedConfiguration.resolve.alias['@src'] = path.resolve(__dirname, '..', 'lib');
generatedConfiguration.resolve.alias['@apps'] = path.resolve(__dirname, '..', 'lib/extensions');
return generatedConfiguration;
}
});
}
Open tsconfig.json
file in your root directory and register additional entries by extending the paths
property
"@apps/*": [
"src/extensions/*"
]
"paths": {
"@src/*": [
"src/*"
],
"@components/*": [
"src/components/*"
],
"@webparts/*": [
"src/webparts/*"
],
"@apps/*": [
"src/extensions/*"
]
},
NOTE: In this file, you should use the
src
folder!
If you use spfx-fast-serve
, webpack must also be extended or the fast-serve/webpack.extend.js
file and the property webpackConfig.resolve.alias
.
"@apps": path.resolve(__dirname, "..", "src/extensions")
NOTE: In this file, you should use the
src
folder!
const webpackConfig = {
/* CUSTOM ALIAS START */
resolve: {
alias: {
"@webparts": path.resolve(__dirname, "..", "src/webparts"),
"@components": path.resolve(__dirname, "..", "src/components"),
"@src": path.resolve(__dirname, "..", "src"),
"@apps": path.resolve(__dirname, "..", "src/extensions")
}
},
/* CUSTOM ALIAS END */
}
As mentioned above, the CLI is based on my personal tips and experiences. Many of the commands or what they do are explained individually in the following articles: