@portalsdev/generator-spfx

PortalsDev SPFx Generator

A tool that will generate code to be used inside SPFx projects.

Install

npm install -g @portalsdev/generator-spfx
npm install -g bit-bin

Make sure you can do the following before running the generator:

mkdir bitTest
cd bitTest
bit init
bit import droopytersen.portalsdev/appcustomizers/menu

A lot of our sub generators rely on Bit. You will need to configure your ssh key and make sure you are a collaborator on the portalsdev scope.

Project Generator

Creates a new SPFx clientside project. To use it, invoke the generator in any folder that doesn't already contain a package.json. It will ask you if you want to use the current folder or create a subfolder.

yo @portalsdev/spfx

├── config
│   ├── config.json
│   ├── copy-assets.json
│   ├── deploy-azure-storage.json
│   ├── package-solution.json
│   ├── serve.json
│   ├── tslint.json
│   └── write-manifests.json
├── src
├── gulpfile.js
├── package.json
├── README.md
└── tsconfig.json

Lastly, don't forget to run an npm install.

What does it do exactly?

• Runs the @microsoft/sharepoint generator
• Configures the project for local webpart development
• Adds /tasks/deploy.ps1 so you can automatically deploy to your Dev App Catalog
• Cleans up /config/config.json
  • Renames your bundle to be project scoped instead of a separate bundle for each component
• Initializes Bit
  • Makes /src/{namespace}/{name} the default Bit component path
• Adds PnP Controls and PnP Components
  • Registers dependency in package.json
  • Configures localizedResources in /config/config.json

Web Part Generator

Creates a the SPFx Web Part files and adds the component to bundle. To use it, invoke the generator from inside your existing SPFx project.

yo @portalsdev/spfx

This will create 4 files for you and register your new component inside of /config/config.json.

My Groups Web Part Generator

1. Pulls down the Bit Component droopytersen.portalsdev/components/sortable-list
2. Pulls down the Bit Component droopytersen.portalsdev/webparts/mygroups
3. Adds the component the the config.json bundle

Component Installer Generator

1. Pulls down the Bit Component droopytersen.portalsdev/webparts/component-installer
2. Adds the component the the config.json bundle

Menu (TopNav) Generator

1. Pulls down the Bit Component droopytersen.portalsdev/appcustomizers/menu
2. TEMPORARY - Updates the project to React 16
3. TEMPORARY - Overrides the Gulp Config to support React 16
4. Adds the component the the config.json bundle
5. Adds a line to the end of /tasks/install.ps1 to call /src/appcustomizers/menu/tasks/install.ps1
6. Modifies /config/serve.json to launch in extension debug mode

Top Nav Implementation Example

A top nav needs a Menu application customizer and the Component Installer webpart

VSTS Setup

Setup the SPARK Site

1. Connect to the admin site
2. Create a new Communication Site
3. Setup a Site Collection App Catalog

o365 spo connect https://skylinespark-admin.sharepoint.com
o365 spo site add --type CommunicationSite --url https://skylinespark.sharepoint.com/sites/testclient --title "Test Client Site"
o365 spo site appcatalog add --url https://skylinespark.sharepoint.com/sites/testclient 

Generate the Project

1. Run yo @portalsdev/spfx

> yo @portalsdev/sfpx
? What do you want?
 (*)  New SPFx Project
 ( )    webparts/ Blank Web Part
 (*)    webparts/ Component Installer
 (*)    appcustomizers/ Custom Menu (TopNav)

2. Install dependencies with yarn install (or npm)
3. Commit source code

git add -A
git commit -m "generated project"

Build/Package/Deploy/Install

1. Build and Package w/ Gulp

gulp bundle --ship
gulp package-solution --ship

2. Manually deploy because the PnP deploy commands currently only support tenant app catalog
   • In a browser open <Your Site>/AppCatalog
   • Drop in the spkg file from /sharepoint/solution
3. Provision the Menu Lists and Seed Data

.\tasks\install.ps1

Setup the Admin Page

1. Create a new page on the site named Admin.aspx
2. Add the Component Installer web part
3. Configure it:

Name=TopNav
Location=ClientSideExtension.ApplicationCustomizer
ClientSideComponentId="c2de4f7d-5979-49dc-9b52-b81ccc1630b7"
ClientSideComponentProperties={
    "menuType":"TopNav",
    "menuSiteUrl:"<SITE w/ MENU LISTS>"
}

4. Use the configured web part to Install the Top Nav on the client site