honeymoose
/
sp-dev-fx-webparts
mirror of https://github.com/pnp/sp-dev-fx-webparts.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Added diagram

Hugo Bernier 2022-03-26 22:52:19 -04:00
parent 3e3ecf6b09
commit ebd3b100e7
1 changed files with 47 additions and 15 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

62
Troubleshooting-issues-with-samples.md

@ -5,14 +5,41 @@ This article should help you resolve the majority of issues, starting with the m
Once you have performed the steps in this article, you can proceed with creating an issue -- but make sure to read [how to create good issues](How-to-create-good-issues) first, because the people who support these samples are all volunteers, and we certainly want to be respectful of their time, *don't we*?
```mermaid
sequenceDiagram
A->> B: Query
B->> C: Forward query
Note right of C: Thinking...
C->> B: Response
B->> A: Forward response
graph TD
A[Get web part sample code]
A -->|Open repo/unzip folder| B(npm install)
B --> C{Any errors?}
C -->|Yes| D{In same folder as package.json?}
C -->|No| E(gulp build)
E --> F{Does in build?}
D -->|No| G(Change directory) --> |Retry|B
D -->|Yes| H{Path too long?}
H -->|Yes| I(Change directory) --> |Retry|B
H -->|No| J(Run spfx doctor)
click J "https://github.com/pnp/sp-dev-fx-webparts/wiki/Troubleshooting-issues-with-samples#run-spfx-doctor"
J --> K{Compatibilty issues?} -->|Yes| L(Fix Compatibilty issues) -->|Retry|B
J -->|No| M(Open an issue)
```
## `npm install` stops with errors
Please note that warnings will rarely prevent the solution from working; We only worry about errors.
### `npm WARN saveError ENOENT: no such file or directory`
Make sure that you are running `npm install` in the root folder where the web part code is located. There should be an existing `package.json` file. **Do not** create a `package.json`, because the solution must already have one -- otherwise it would not have been accepted as a sample.
If you're already currently in the root of the sample solution, take a look to see if the sample contains sub-components; are there any folders named `webparts` (or something similar)? If so, try looking for the `README.md` for instructions on how to build the sample.
### `Build FAILED`
You should see at least one line showing `npm ERR!` in the many many lines of diagnostics after running `npm install`.
Look for messages such as `Not compatible with your version of node/npm`.
Try [#run-spfx-doctor](running `spfx doctor`) to make sure your environment is compatible with the solution.
## Sample won't build
![Symptoms: Won't build](https://img.shields.io/badge/Symptoms-Won%27t%20build-critical?style=for-the-badge&logo=nodedotjs)
@ -23,12 +50,12 @@ Every version of SPFx can be compatible with a different version of Node.js. If
You can see a full list of SPFx versions and the supported environment in the [SPFx Compatibility Matrix](https://docs.microsoft.com/en-us/sharepoint/dev/spfx/compatibility).
Every sample's `README.md` file contains a **Compatibility** section, indicating the version of **SPFx** and the **Node.js** version compatibility for that sample.
Every sample's `README.md` file contains a **Compatibility** section, indicating the version of **SPFx** and the **Node.js** version compatibility for that sample.
Look for visual tags such as these:
![SPFx 1.12.1](https://img.shields.io/badge/SPFx-1.12.1-green.svg)
![Node.js v14 | v12 | v10](https://img.shields.io/badge/Node.js-v14%20%7C%20v12%20%7C%20v10-green.svg)
![Node.js v14 | v12 | v10](https://img.shields.io/badge/Node.js-v14%20%7C%20v12%20%7C%20v10-green.svg)
The **SPFx** version indicates which version of the SPFx Yeoman generator was used to build the sample. It *does not need to match the version of the generator currently installed on your workstation* -- unless you are trying to add new SPFx components to the sample (something that you should only consider *after* you get the solution to build successfully).
@ -76,6 +103,7 @@ To do so, follow these steps:
```bash
npm i -g @pnp/cli-microsoft365
```
1. With the CLI installed, change your command prompt's current directory to the root of the sample's solution. Although it is often the same folder containing the `README.md`, some more complex samples may have multiple solutions in multiple sub-folders. The root will contain a `package.json`.
You can confirm that you are within the solution's root folder by using your command prompt to enter the following command:
@ -83,20 +111,21 @@ To do so, follow these steps:
```bash
ls package.json
```
If it returns a single `package.json`, you are in the right folder. If you get `ls: cannot access 'package.json': No such file or directory`, make sure to change the current folder (using `cd `, followed by the full path of where your sample is stored).
If it returns a single `package.json`, you are in the right folder. If you get `ls: cannot access 'package.json': No such file or directory`, make sure to change the current folder (using `cd`, followed by the full path of where your sample is stored).
1. Using your command prompt, enter the following command:
```bash
m365 spfx doctor -o text
```
The command will analyze your environment against the solution. You should see results that begin with the following text:
CLI for Microsoft 365 SharePoint Framework doctor
Verifying configuration of your system for working with the SharePoint Framework
1. If your environment is configured correctly, you will get a series of checkmarks (`√`), for example:
1. If your environment is configured correctly, you will get a series of checkmarks (`√`), for example:
√ SharePoint Framework v1.13.1
√ Node v12.20.2
@ -107,22 +136,25 @@ To do so, follow these steps:
× react v10.8.5 found, v16.9.51 required
1. If you received one or more checkmarks, follow the **Recommended fixes:** generated by `spfx doctor`. For example:
1. If you received one or more checkmarks, follow the **Recommended fixes:** generated by `spfx doctor`. For example:
Recommended fixes:
- npm i react@16.9.51
1. Follow each recommended fixes and repeat the `spfx doctor` command until you can confirm that your environment is compatible with the sample.
1. If you still cannot resolve the issue, run `spfx doctor` to generate a `json` output, and submit a new issue, making sure to copy the output of to the **SPFx doctor** section. You can do so by using the command prompt to enter the following command:
1. Follow each recommended fixes and repeat the `spfx doctor` command until you can confirm that your environment is compatible with the sample.
1. If you still cannot resolve the issue, run `spfx doctor` to generate a `json` output, and submit a new issue, making sure to copy the output of to the **SPFx doctor** section. You can do so by using the command prompt to enter the following command:
```bash
m365 spfx doctor -o json
```
Copy the output and [open a new bug report](https://github.com/pnp/sp-dev-fx-webparts/issues/new?assignees=&labels=type%3Abug-suspected&template=bug-report.yml)
### Alternatives
#### Recommended
If you are unable to update your environment to run the solution, consider the following alternatives:
- [Open the sample in a remote container](https://github.com/pnp/sp-dev-fx-webparts/wiki/Opening-a-sample-using-a-development-container)
@ -130,4 +162,4 @@ If you are unable to update your environment to run the solution, consider the f
#### Not recommended
- **Upgrade the sample:** You may be tempted to upgrade the sample to the latest version of SPFx, but doing so may take some time and you may find out that the sample no longer works, or does not meet your needs. Furthermore, you may introduce new bugs that were previously not found in the original version. You should only invest the time to upgrade a sample if you can confirm that the sample works in within a compatible environment, and if you need to add new capabilities that are not supported in previous versions of SPFx, or to fix a vulnerability which can only be fixed with newer versions of SPFx, Node.js, or solution dependencies.
- **Upgrade the sample:** You may be tempted to upgrade the sample to the latest version of SPFx, but doing so may take some time and you may find out that the sample no longer works, or does not meet your needs. Furthermore, you may introduce new bugs that were previously not found in the original version. You should only invest the time to upgrade a sample if you can confirm that the sample works in within a compatible environment, and if you need to add new capabilities that are not supported in previous versions of SPFx, or to fix a vulnerability which can only be fixed with newer versions of SPFx, Node.js, or solution dependencies.