|
| 1 | +--- |
| 2 | +title: Yeoman generator for the SharePoint Framework |
| 3 | +description: On this page, learn how to use the Yeoman generator for the SharePoint Framework to create SPFx projects. |
| 4 | +ms.date: 02/08/2022 |
| 5 | +ms.prod: sharepoint |
| 6 | +ms.localizationpriority: high |
| 7 | +--- |
| 8 | +# Yeoman generator for the SharePoint Framework |
| 9 | + |
| 10 | +The **SharePoint Online SPFx Yeoman Generator** helps you quickly create a SharePoint client-side solution project with the right toolchain and project structure. It's used along with Yeoman to prompt you with questions to create the project scaffolding (the folders & files). |
| 11 | + |
| 12 | +> [!IMPORTANT] |
| 13 | +> This page assumes you've already installed all the necessary prerequisites for developing SharePoint Framework solutions. Verify the updated instructions outlined in the page [Set up your SharePoint Framework development environment](set-up-your-development-environment.md). |
| 14 | +
|
| 15 | +The SharePoint Online SPFx Yeoman Generator (*the "SPFx generator"*), uses the responses to the questions the developer is prompted with to create a new SharePoint Framework (SPFx) project. Depending on some prompt responses, other questions are presented. |
| 16 | + |
| 17 | +For example, if you select the **WebPart** component type, you'll only see questions for the web part name and template type. However, if you select the **Extension** component type, you'll also be prompted for the type of extension such as application customizer, field customizer, or ListView command set. |
| 18 | + |
| 19 | +The following demonstrates the creation of a new solution named **sfpxplay-01** in the current folder with a web part named **HelloWorld** that uses the **Minimal** project template: |
| 20 | + |
| 21 | +```console |
| 22 | +yo @microsoft/sharepoint --skip-install |
| 23 | + |
| 24 | + _-----_ ╭──────────────────────────╮ |
| 25 | + | | │ Welcome to the │ |
| 26 | + |--(o)--| │ SharePoint Online SPFx │ |
| 27 | + `---------´ │ Yeoman │ |
| 28 | + |
| 29 | + /___A___\ /╰──────────────────────────╯ |
| 30 | + | ~ | |
| 31 | + __'.___.'__ |
| 32 | + ´ ` |° ´ Y ` |
| 33 | + |
| 34 | +Let's create a new SharePoint solution. |
| 35 | +? What is your solution name? spfxplay-01 |
| 36 | +? Which type of client-side component to create? WebPart |
| 37 | +Add new Web part to solution spfxplay-01. |
| 38 | +? What is your Web part name? HelloWorld |
| 39 | +? Which template would you like to use? Minimal |
| 40 | + |
| 41 | + create package.json |
| 42 | + force .yo-rc.json |
| 43 | + create config/package-solution.json |
| 44 | + create config/config.json |
| 45 | + create config/serve.json |
| 46 | + create tsconfig.json |
| 47 | + create .vscode/launch.json |
| 48 | + create .vscode/settings.json |
| 49 | + create config/deploy-azure-storage.json |
| 50 | + create config/write-manifests.json |
| 51 | + create src/index.ts |
| 52 | + create README.md |
| 53 | + create .gitignore |
| 54 | + create .npmignore |
| 55 | + create gulpfile.js |
| 56 | + create tslint.json |
| 57 | + create src/webparts/helloWorld/loc/en-us.js |
| 58 | + create src/webparts/helloWorld/loc/mystrings.d.ts |
| 59 | + create src/webparts/helloWorld/HelloWorldWebPart.module.scss |
| 60 | + create src/webparts/helloWorld/HelloWorldWebPart.ts |
| 61 | + create src/webparts/helloWorld/HelloWorldWebPart.manifest.json |
| 62 | + create teams/55564fc2-179d-4bc1-bd63-9ede8183dadc_outline.png |
| 63 | + create teams/55564fc2-179d-4bc1-bd63-9ede8183dadc_color.png |
| 64 | + |
| 65 | +Changes to package.json were detected. |
| 66 | +Skipping package manager install. |
| 67 | + |
| 68 | + _=+#####! |
| 69 | + ###########| .------------------------------------. |
| 70 | + ###/ (##|(@) | Congratulations! | |
| 71 | + ### ######| \ | Solution spfxplay-01 is created. | |
| 72 | + ###/ /###| (@) | Run gulp serve to play with it! | |
| 73 | + ####### ##| / '------------------------------------' |
| 74 | + ### /##|(@) |
| 75 | + ###########| |
| 76 | + **=+####! |
| 77 | +``` |
| 78 | + |
| 79 | +> [!TIP] |
| 80 | +> The different component types and options are addressed throughout the documentation in this site. Every option isn't covered on this page. For more information about the details on each component type, see the relevant topics throughout the documentation. |
| 81 | +
|
| 82 | +## Project template options |
| 83 | + |
| 84 | +Prior to SPFx v1.14, the generator provided developers with two project templates: |
| 85 | + |
| 86 | +- **No JavaScript Framework**: |
| 87 | +- **React** |
| 88 | + |
| 89 | +> [!NOTE] |
| 90 | +> A third option, **Knockout**, was available in all SPFx releases through SPFx v1.10. Knockout was retired as an option in SPFx v1.11. |
| 91 | +
|
| 92 | +These templates included the minimal code a project needed to get started creating solutions. The **No JavaScript Framework** template used HTML and CSS to style a basic component while the **React** template used HTML, React, and CSS to do the same thing. |
| 93 | + |
| 94 | +### Project templates updated in SPFx v1.14 with theme-support |
| 95 | + |
| 96 | +In the SPFx v1.14 release, the SPFx generator introduced new & updated project templates. The goal of these templates is to include the code necessary to support the theme in the current environment where the component is running (SharePoint or Microsoft Teams). |
| 97 | + |
| 98 | +The code included in these templates simplifies the initial work developers must do in order to add support for themes to their components. For example, using these templates, all the code necessary to determine the colors and font used in the current SharePoint site are available within the web part and the web part will be notified when the theme changes to pick up the new theme settings. |
| 99 | + |
| 100 | +For SPFx components used in the context of Microsoft Teams, they'll receive the theme details for the current Microsoft Teams client such as default (light), dark, and high contrast. |
| 101 | + |
| 102 | +Furthermore, these templates include the code to determine if the component is currently running in a SharePoint context, or a Microsoft Teams context. |
| 103 | + |
| 104 | +For example, the following methods are included in both templates. The `_getEnvironmentMessage()` method returns a string indicating if the component is currently running in SharePoint or Microsoft Teams and if it's deployed to production or in development (served from localhost). The `onThemeChanged()` determines if the current theme is in dark mode and applies some changes to properties based on the current theme colors: |
| 105 | + |
| 106 | +```typescript |
| 107 | +private _getEnvironmentMessage(): string { |
| 108 | + if (!!this.context.sdks.microsoftTeams) { // running in Teams |
| 109 | + return this.context.isServedFromLocalhost |
| 110 | + ? strings.AppLocalEnvironmentTeams |
| 111 | + : strings.AppTeamsTabEnvironment; |
| 112 | + } |
| 113 | + |
| 114 | + return this.context.isServedFromLocalhost |
| 115 | + ? strings.AppLocalEnvironmentSharePoint |
| 116 | + : strings.AppSharePointEnvironment; |
| 117 | +} |
| 118 | + |
| 119 | +protected onThemeChanged(currentTheme: IReadonlyTheme | undefined): void { |
| 120 | + if (!currentTheme) { |
| 121 | + return; |
| 122 | + } |
| 123 | + |
| 124 | + this._isDarkTheme = !!currentTheme.isInverted; |
| 125 | + const { |
| 126 | + semanticColors |
| 127 | + } = currentTheme; |
| 128 | + this.domElement.style.setProperty('--bodyText', semanticColors.bodyText); |
| 129 | + this.domElement.style.setProperty('--link', semanticColors.link); |
| 130 | + this.domElement.style.setProperty('--linkHovered', semanticColors.linkHovered); |
| 131 | + |
| 132 | +} |
| 133 | +``` |
| 134 | + |
| 135 | +### Minimal project template |
| 136 | + |
| 137 | +A new project template option, **Minimal**, was added to the SPFx generator in SPFx v1.14. This project template option includes no theme or host environment code in new projects. |
| 138 | + |
| 139 | +For example, a new web part project starts with the following code, representing the minimal code necessary to run the web part: |
| 140 | + |
| 141 | +```typescript |
| 142 | +export default class HelloWorldMinimalWebPart |
| 143 | + extends BaseClientSideWebPart<IHelloWorldMinimalWebPartProps> { |
| 144 | + |
| 145 | + protected onInit(): Promise<void> { |
| 146 | + return super.onInit(); |
| 147 | + } |
| 148 | + |
| 149 | + public render(): void { |
| 150 | + this.domElement.innerHTML = `<div class="${ styles.helloWorldMinimal }"></div>`; |
| 151 | + } |
| 152 | + |
| 153 | + protected get dataVersion(): Version { |
| 154 | + return Version.parse('1.0'); |
| 155 | + } |
| 156 | +} |
| 157 | +``` |
| 158 | + |
| 159 | +## Retired generator prompts |
| 160 | + |
| 161 | +With each release of the SharePoint Framework, prompts may be added or removed in the Yeoman generator. Prompts were removed to simplify the project creation experience. |
| 162 | + |
| 163 | +In the following section, you'll find the retired prompts with applicable guidance. |
| 164 | + |
| 165 | +### Target different SharePoint Environments |
| 166 | + |
| 167 | +In the [SPFx v1.13 release](release-1.13.md), the following prompt was retired: |
| 168 | + |
| 169 | +> Which baseline packages do you want to target for your component(s)? |
| 170 | +
|
| 171 | +This prompt presented the developer with the option to create a project that targeted specific SharePoint deployments, including: |
| 172 | + |
| 173 | +- **SharePoint Online only (latest)** |
| 174 | +- **SharePoint 2016 onwards, including 2019 and SharePoint Online** |
| 175 | +- **SharePoint 2019 onwards, including SharePoint Online** |
| 176 | + |
| 177 | +Starting with SPFx v1.13, the generator can only create projects for SharePoint Online. |
| 178 | + |
| 179 | +### Skip feature deployment - `skipFeatureDeployment` |
| 180 | + |
| 181 | +In the [SPFx v1.14 release](release-1.14.md), the following prompt was retired: |
| 182 | + |
| 183 | +> Do you want to allow the tenant admin the choice of being able to deploy the solution to all sites immediately without running any feature deployment or adding apps in sites? |
| 184 | +
|
| 185 | +This question is asking if the solution should be automatically installed for all sites in the tenant, or should it be manually installed in each site? The default option was **\[N\]o**. |
| 186 | + |
| 187 | +> [!NOTE] |
| 188 | +> Learn more about this prompt: [Tenant-scoped solution deployment for SharePoint Framework solutions](tenant-scoped-deployment.md). |
| 189 | +
|
| 190 | +The outcome of this question was set on the `skipFeatureDeployment` property in the project's **./config/package-solution.json** file. |
| 191 | + |
| 192 | +Starting with SPFx v1.14, the `skipFeatureDeployment` property defaults to `true`. You can change the value of this property after creating the project, if necessary. |
| 193 | + |
| 194 | +### Domain isolated web parts - `isDomainIsolated` |
| 195 | + |
| 196 | +In the [SPFx v1.14 release](release-1.14.md), the following prompt was retired: |
| 197 | + |
| 198 | +> Will the components in the solution require permissions to access web APIs that are unique and not shared with other components in the tenant? |
| 199 | +
|
| 200 | +This question is asking if the web parts within the solution should be rendered within an IFRAME in a unique ___domain, or in a DIV as the current page. The default option was **\[N\]o**. |
| 201 | + |
| 202 | +> [!NOTE] |
| 203 | +> Learn more about this prompt: [Isolated web parts](web-parts/isolated-web-parts.md) |
| 204 | +
|
| 205 | +The outcome of this question was set on the `isDomainIsolated` property in the project's **./config/package-solution.json** file. |
| 206 | + |
| 207 | +Starting with SPFx v1.14, the `isDomainIsolated` property defaults to `false`. You can change the value of this property after creating the project, if necessary. |
| 208 | + |
| 209 | +### Which framework would you like to use? |
| 210 | + |
| 211 | +In the [SPFx v1.14 release](release-1.14.md), the following prompt was changed: |
| 212 | + |
| 213 | +> Which framework would you like to use? |
| 214 | +
|
| 215 | +This prompt was displayed for specific project types, such as web parts & types of SPFx extensions. It enabled developers to select from different project templates: **No JavaScript framework** or **React**. |
| 216 | + |
| 217 | +The default project scaffolding created by the Yeoman generator was determined using the option selected. |
| 218 | + |
| 219 | +In SPFx v1.14, this prompt was changed to the following and presented the user with three choices: **Minimal**, **No framework**, or **React**: |
| 220 | + |
| 221 | +> Which template would you like to use? |
| 222 | +
|
| 223 | +### Component descriptions |
| 224 | + |
| 225 | +In the [SPFx v1.14 release](release-1.14.md), the following prompts were retired: |
| 226 | + |
| 227 | +> What is your Web part description? |
| 228 | +> |
| 229 | +> What is your Application Customizer description? |
| 230 | +> |
| 231 | +> What is your Field Customizer description? |
| 232 | +> |
| 233 | +> What is your ListView Command Set description? |
| 234 | +> |
| 235 | +> What is your Library description? |
| 236 | +> |
| 237 | +> What is your Adaptive Card Extension description? |
| 238 | +
|
| 239 | +The values of these prompts were set on the `preConfiguredEntries[0].description.default` & `preConfiguredEntries[0].properties.description` properties in the component's **\*.manifest.json** file. |
| 240 | + |
| 241 | +Starting with SPFx v1.14, these properties are set to empty strings. You can change the value of these properties after creating the project, if necessary. |
0 commit comments