Pull request checklist
- [x] Addresses an existing issue: Part of #14691
- [x] Include a change request file using
$ yarn change
Description of changes
Best viewed with "ignore whitespace changes" (for a couple of the files)
Previously, several pieces of setup code for the public website (developer.microsoft.com/fluentui) and its local/PR deployed versions had to be duplicated across every major version branch of Fluent/Fabric. This was not ideal since the process of making updates (such as adding a new major version) was very manual and error-prone.
This PR adds and uses a new package @fluentui/public-docsite-setup
(open to naming suggestions) to de-duplicate website setup tasks, including:
- Loading the real site (developer.microsoft.com/fluentui): get the "manifest" file for the requested (or latest) major version, then load the current website build for that major version
- Loading the local or PR deploy site
- Setting up the version switcher definition (also provides related types)
Build setup
The build steps/configuration related to this change are as follows. (These build steps will also be added in the 5.0
, 6.0
, and 7.0
branches, using the @fluentui/public-docsite-setup
package from master
.)
Some of this is also explained in the public-docsite-setup
readme.
| File/pipeline | What's called/done | Details |
|--|--|--|
| apps/public-docsite
webpack configs | getLoadSiteConfig()
from under @fluentui/public-docsite-setup/scripts/
| Adds a webpack config that generates dist/loadSite.js
(for actual loading) and copies shared index.html
to website's dist
folder |
| Release pipeline azure-pipelines.release.yml
| yarn create-site-manifests [main package path] [CDN URL root]
(script is from @fluentui/public-docsite-setup
's bin
) | Generates "manifest" files (under site-manifests/v8-prod.js
and v8-df.js
) with:
- the URL where files from that build will be uploaded
- the full version of @fluentui/react
|
| Release pipeline azure-pipelines.release.yml
| "Publish artifact: fabric-website-manifests" task | Uploads the generated manifest files as a build artifact |
| Website release pipeline (internal) | Upload manifest files to live location | |
Additional manual step (as needed): since the live site actually uses bootstrap code stored in an internal repo, manually copy apps/public-docsite/homepage.htm
and apps/public-docsite/dist/loadSite.js
to the internal repo
What happens at runtime
At runtime, we start with the HTML file loading the loadSite.js
bundle. (The bundle is generated by webpack from @fluentui/public-docsite-setup/src/loadSite.ts
, using the getLoadSiteConfig()
helper.)

The version switcher definition is read from the global by apps/public-docsite/src/SiteDefinition/SiteDefinition.tsx
, and various places in the site consume it from there.
Here's a text version with more detail.
- HTML file loads
loadSite.js
bundle (it's generated by webpack from @fluentui/public-docsite-setup/src/loadSite.ts
using getLoadSiteConfig
)
loadSite.js
does the actual loading:
- Check
location.hostname
to determine which variant of the site this is (localhost, PR deploy, prod, df)
- If localhost or PR deploy:
- Get the full version of
@fluentui/react
being demoed from process.env.LOCAL_LIBRARY_VERSION
(set by webpack helper)
- Call
loadSiteInternal
with that version and using the current URL as the base URL for files from that website build
- If it's the real site (prod/df):
- Determine the major version to load: use
?fabricVer=N
from URL, or default to latest
- Load the "manifest" file for that major version:
vN-df.js
or vN-prod.js
- Call
loadSiteInternal
with the base URL and full library version from the manifest
- In
loadSiteInternal
:
- Set up the version switcher definition global (basically a bunch of
IContextualMenuItem
s with pre-defined click handlers for reloading with a new version)
- Note: in localhost/PR deploy builds, the click handler just displays an alert saying you can't switch versions. This is to avoid previous issues where the site implicitly loaded the live files for other versions (or even the current version), making it seem like you're testing your changes when in fact you're not.
- Set up global
MonacoConfig
for the example editor
- Load the root file of the actual site (minified or unminified as appropriate) from the given base URL
- The site is loading!
- Actual version switcher setup:
apps/public-docsite/src/SiteDefinition/SiteDefinition.tsx
gets the version switcher definition from the global, and various places in the site consume it from there.
Open questions
As the PR is now, there's quite a mix of "fabric" or not in naming. Open for suggestions for what to do here. (Also okay with just going with it as-is.)
| Thing | Name | Notes |
|--|--|--|
| Main website webpack bundle | fabric-site
| A slight improvement over previous name fabric-sitev5
. Could let this vary across branches, but it's easiest if we don't. |
| Website-related artifacts in azure-pipelines.release.yml
| fabric-website-whatever
| Again easiest if these stay the same across branches. Inclined to leave as-is to reduce work updating the website release pipeline (and slightly reduce churn in old branches). |
| Shared setup package | public-docsite-setup
| Follows website naming convention from master
. Will be used in other branches but that's probably fine. |
| Shared bootstrap file | loadSite.ts
/.js
| |
| Types from shared package | SiteConfig
, SiteGlobals
| |
| Manifest creation script | create-site-manifests
| |
| Generated manifest files | site-manifests/vN-prod.js
| |
| Global defined by manifest files | __siteConfig
| |
Area: Website PR: API Modified