Base Portal Implementation

Usage no npm install needed!

<script type="module">
  import sfdocsInternalPortal from 'https://cdn.skypack.dev/@sfdocs-internal/portal';



Base Package to define a portal that aggregates Writer Asset Repositories into a Site.

While Writer Asset Repositories can also be standalone sites, they are not capable of orchestrating several repositories into a portal.

Portal Start

When the portal starts, these tasks are performed:

  • Read the configuration of the site
  • Resolve the list of doc repositories ( writer asset repos ), through fetching or linking
  • Dynamically generate routes for repo content
  • Start the LWR server

Portal Local Repository Linking

The portal has the ability to 'link' an external repository URL with a repository folder on the local file system, which would then configure the build step to read from the local repository folder and not be downloaded from the given github URL. This 'link' step would need to be run before calling portal.start().

This is done by performing the linking cli command for each local repository prior to starting the portal.

For example, to link the github repo https://github.com/salesforcedocs/example to a local clone of the repository under /home/user/example, run:

sfdocs portal . --link-repo=https://github.com/salesforcedocs/example --link-dir=/home/user/example

Github Authentication

Access to private writer asset repositories in Github is done using Github Apps authentication.

Credentials may be supplied on the local development environment as files under the credentials folder or through environement variables.

Local dev

When developing locally, you'll want the build to use the certificates directory on the file system vs the environment variables. If you do not have the environment variables GITHUB_APP_ID and GITHUB_CERTIFICATE_PATH specified then it'll use the local file system directory specified in the configuration.certificatesDir property. Alternatively, you could specify LOCAL_DEV=1 as an environment variable to toggle local mode.

config.certificatesDir - The location of certificates on the local file system to use for authentication. Used only when specfied for running local development.

To setup credential files for local development check out this readme

Supply credentials through ENV

Supply these environment variables when running the app:

GITHUB_APP_ID=<ID of your Github App>
GITHUB_CERTIFICATE_BASE64=<Certificate plaintext encoded in base64>

You may also create a .env file with these variables and specifying the env file in a VSCode VSCode launch command:

    "configurations": [
            "type": "node",
            "envFile": "${workspaceFolder}/.env"