Skip to content
SPFx Toolkit

Technical Reference & Contributing Guidelines

🙋‍♂️ Contribution guidance

Section titled “🙋‍♂️ Contribution guidance”

👉 Before you start working on an issue, be sure to check out our Contribution guidelines👍.

👉 Repository branches

Section titled “👉 Repository branches”

You may have already noticed that this repo maintains two branches: main and dev. What’s even more important is that every feature branch should be created based on dev branch and Pull Requests should target dev branch not main. It’s important to understand why the meaning and purpose of each branch:

  • main - based on this branch new major and minor releases are created. Only critical bug fixes or feature updates go directly to this branch. All others should first be merged to dev branch and then merged to from dev to main with a separate PR. This branch is main repository branch and keeping clean changes history is important.
  • dev - based on this branch pre-releases are created. Every change should be merged to this branch first with a PR before they get merged to main branch. During the release flow, this branch may be rebased and force pushed against main branch, so it may be recreated based on the current main branch state.

📃 Solution details

Section titled “📃 Solution details”

The project is a VS Code extension that uses many typical VS Code extension components like panels, providers, commands, webviews etc.

👉 Project structure

Section titled “👉 Project structure”

The main definition of the project is (as always) in the package.json file. Besides the dependencies in that file, we may find most of the VS Code extension capabilities (some almost fully defined like welcome experience or walkthrough or commands) and details present in the VS Code marketplace.

├── assets // Keeps all the graphical files connected to the project (either used in the extension or in docs)
│   └── images // Keeps images used in readme file
├── data // Keeps .json files which store info about all the samples or scenarios of a given PnP sample gallery repo
├── scripts // Keeps all the scripts used for maintenance or in pipelines
├── src
│   ├── chat // GitHub Copilot participant related files
│   ├── constants // Types, dictionary data, or static strings
│   ├── models // Models/interfaces used as method inputs or outputs
│   ├── panels // Panels are the sections you see in the action pane. Here we decide if we show welcome experience or the SPFx project panels and what is their behavior
│   ├── providers
│   ├── services // Groups functionalities dedicated to a specific feature or service (like Scaffolder)
|   ├── tests
│   ├── utils // Groups all small helper methods
│   ├── webview // Groups all webviews used in this extension
│   └── extension.ts // Main point of the extension that runs on start and registers all other components
├── syntaxes
├──  webpack
├── .eslintrc.json
├── .vscodeignore
├── postcss.config.js
├── tailwind.config.js
└──  tsconfig.json

👉 Tech used

Section titled “👉 Tech used”

The extension was developed using the following tech:

  • CLI for Microsoft 365
  • React.js
  • TypeScript
  • Tailwindcss
  • Webpack

👉 Extension Capabilities

Section titled “👉 Extension Capabilities”

The extension uses the following VS Code extension capabilities:

🦾 Pipelines

Section titled “🦾 Pipelines”

Currently in the project we have 4 pipelines:

  • Pre-Release - This pipeline should be used only for dev branch. It is only possible to trigger this pipeline manually. The aim is to release a VSCode extension version as a Pre Release so specifying --pre-release option. It should be used to deliver the latest features that were developed and will be released with a new major or minor version, so that it may be tested in a pre-release (beta) in order to collect feedback. Before this pipeline is started we should check if:
    • in the package.json file the version was increased in the patch section. So for example x.y.1
  • Main Release - This pipeline should be used only for main branch. It is possible to trigger it manually but also it will be started when a new release is issued via GitHub (so a new tag is created as well). It should be used to deliver a new major or minor version of the extension. Before this pipeline is started we should check if:
    • in the package.json file the version was increased in either major or minor parts. So for example 1.1.x
    • the changelog file was updated with details for the new release
    • all the new features are documented in the wiki and added to the readme file
    • a vsce package is created so that it may be included in the release
  • Update samples data - It actually does not matter on which branch this pipeline will run as it does not work with the source files of this project. It may be triggered manually or it will trigger as scheduled, once a week on Saturday. The aim of this pipeline is to recheck the PnP SPFx web parts, SPFx extensions, ACE’s sample repos and create local json files kept in the data folder which will have the info about each sample. The pipeline creates a PR so that the changes may be reviewed and merged manually (they have to be merged to the main branch). The SharePoint Framework Toolkit uses those files in order to create the sample gallery views. That way allows us to keep the samples up to date without the need to release a new version of the extension. There are no prerequisites that need to be met in order to run this pipeline.
  • Create .vsix package - The aim of this workflow is to create .vsix package to be downloaded from the artifacts and tested locally.

🧪 Tests

Section titled “🧪 Tests”

To run tests in debug:

  1. install extension https://marketplace.visualstudio.com/items?itemName=ms-vscode.extension-test-runner
  2. run npm run package && npm run compile-tests
  3. run Extension Tests in debug

image

To run:

  1. run npm run package && npm run compile-tests
  2. run npm run test and check the result in terminal