@servicetitan/docs-uikit 31.6.0 → 32.0.1

package/docs/BREAKING_CHANGES.mdx

@@ -2,6 +2,24 @@
 title: BREAKING CHANGES
 ---
 
+## v32.0.0
+
+### [@servicetitan/startup](./startup)
+
+:::caution
+This breaking change affects local development, even if you do not update the `@servicetitan/startup` dependency directly. On a clean install, the standard bootstrap script runs the latest version of `startup`, which automatically removes hard-coded tokens from `.npmrc` files.
+:::
+
+Removed support for hard-coded npm tokens in `.npmrc` files. The new `startup install` removes hard-coded authentication tokens from project `.npmrc` files and, in development environments, automatically adds a token to npm's per-user configuration that grants access to ServiceTitan's private packages.
+
+Projects that previously relied on hard-coded tokens must update their Github and Teamcity workflows to instead use the organization secret as described in the [startup install documentation](./startup/install#configuring-npm-token-in-ci):
+
+- Option 1: Inject the organization secret into `.npmrc`.
+- Option 2: Configure `.npmrc` to get the organization secret from an environment variable.
+
+**Why this change?**  
+Two recent incidents mandated that we revoke the shared token that grants access to ServiceTitan's private packages. By removing hard-coded tokens, ServiceTitan can more easily and seamlessly rotate or revoke tokens, improving security and reducing friction for developers.
+
 ## v31.0.0
 
 ### [@servicetitan/startup](./startup)

package/docs/startup/install.mdx

@@ -2,6 +2,9 @@
 title: install
 ---
 
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
 Installs project dependencies.
 
 Use this command instead of plain `npm install` to guarantee that all packages are installed correctly and any necessary post-install steps are performed.
@@ -11,3 +14,151 @@ npx --yes @servicetitan/startup install
 ```
 
 See [package.json in the example project](https://github.com/search?q=repo%3Aservicetitan%2Ffrontend-example+path%3A**%2Fpackage.json+%22startup+install%22&type=code) for how to use `install` in an npm script.
+
+## Options
+
+| Option       | Description                                   |
+| :----------- | :-------------------------------------------- |
+| `--no-token` | Disable configuring npm authentication token. |
+
+## Configuring NPM Token in Development
+
+In development environments, `startup install` automatically configures an npm authentication token that grants access to private ServiceTitan packages. It securely retrieves the token and updates your npm configuration so you can install dependencies without any further setup.
+
+:::caution
+`startup install` detects if it is running in development by checking for standard environment variables set by CI systems (e.g.,`CI` and `TEAMCITY_VERSION`). If none of these variables are set, it assumes it is running on a developer machine.
+If it mistakes a CI environment for a developer machine, add a `CI` environment variable (with any value) to the workflow, or [use `--no-token`](#how-to-use---no-token) to disable configuring the npm token.
+:::
+
+## Configuring NPM Token in CI
+
+In CI environments such as Teamcity and Github, use the `ST_NPM_READONLY_TOKEN` organization secret to grant access to private ServiceTitan packages. You can do this in two ways:
+
+### Option 1: Inject into .npmrc (Recommended)
+
+The recommended method is to use `npm config set --location=project` to manually inject the organization secret into the project's `.npmrc`. For example,
+
+<Tabs
+defaultValue="github"
+values={[{ label: "Github Action", value: "github"}, {label: "Dockerfile", value: "docker"}]}>
+
+<TabItem value="github">
+
+```yml
+- run: npm config set --location=project "//registry.npmjs.org/:_authToken"="${{ secrets.ST_NPM_READONLY_TOKEN }}"
+- run: npm run build
+```
+
+Alternatively, in Github actions using `action/setup-node`, you can use `registry-url` and `env.NODE_AUTH_TOKEN` to have it configure the project level `.npmrc`. For example,
+
+```yml
+- uses: actions/setup-node@v4
+  registry-url: https://registry.npmjs.org
+  env:
+      NODE_AUTH_TOKEN: ${{ secrets.ST_NPM_READONLY_TOKEN }}
+```
+
+</TabItem>
+<TabItem value="docker">
+
+```dockerfile
+ARG NPM_READONLY_TOKEN
+
+RUN npm config set --location=project "//registry.npmjs.org/:_authToken=$NPM_READONLY_TOKEN"
+RUN npm run build
+```
+
+</TabItem>
+</Tabs>
+
+### Option 2: Use environment variable
+
+:::caution
+Using an environment variable is not recommended because it requires [extra steps](#how-to-configure-with-legacy-startup) to rotate the token in projects using `startup` v31 or earlier.
+:::
+
+To use an environment variable to configure the npm token, modify `.npmrc` to get the token from an environment variable,
+
+```npmrc title=".npmrc"
+//registry.npmjs.org/:_authToken=${NPM_READONLY_TOKEN}
+```
+
+Then, in the CI action, set that environment variable to the organization secret. For example,
+
+<Tabs
+defaultValue="github"
+values={[{ label: "Github Action", value: "github"}, {label: "Dockerfile", value: "docker"}]}>
+
+<TabItem value="github">
+
+```yml
+- run: npm run build
+  env:
+      NPM_READONLY_TOKEN: ${{ secrets.ST_NPM_READONLY_TOKEN }}
+```
+
+</TabItem>
+<TabItem value="docker">
+
+```dockerfile
+ARG NPM_READONLY_TOKEN
+
+ENV NPM_READONLY_TOKEN=${NPM_READONLY_TOKEN}
+
+RUN npm run build
+```
+
+</TabItem></Tabs>
+
+## How to Configure Development Environment When Not Using Startup v32 or Later {#how-to-configure-with-legacy-startup}
+
+:::note
+These instructions are only for projects using [Option 2](#option-2-use-environment-variable) with `startup` v31 or earlier (or that are not using `startup` at all);
+`startup` v32 automatically detects and provides environment variables to `npm install`.
+:::
+
+If your project is [using an environment variable](#option-2-use-environment-variable), and it isn't using `startup` v32 or later, then developers must also defined the same environment variable manually. And they must repeat these steps each time the token is rotated,
+
+1. Run `npx --yes @servicetitan/startup@latest install` to add the token to your per-user configuration.
+2. Run `npm config get userconfig` to get the location of your per-user configuration file.
+3. Find the token in the configuration file, on the line that starts `//registry.npmjs.org/:_authToken=`
+4. Create a local environment variable with the token. Use the same variable name as in project's `.npmrc`.
+
+:::tip
+On MacOS you can accomplish steps 2 and 3 with this single command:
+
+```sh
+grep registry.npmjs.org < $(npm config get userconfig)
+```
+
+:::
+
+## How to Use --no-token
+
+If startup mistakes your CI environment for a development machine and it isn't practical to add a `CI` environment variable to the workflow, use `--no-token` to instruct `startup install` not to attempt to configure the npm token.
+
+Create a `build:ci` script and accompanying pre script that runs `bootstrap` with `-- --no-token`:
+
+```json title="package.json"
+    "scripts": {
+        "prebuild:ci": "npm run bootstrap -- --no-token",
+        "build:ci": "startup build"
+    },
+```
+
+Then, call `build:ci` instead of `build` in the CI workflow:
+
+```sh
+npm run build:ci
+```
+
+:::note
+This assumes you're using this recommended `bootstrap` script:
+
+```json
+    "scripts": {
+        "bootstrap": "npx --yes @servicetitan/startup install",
+    }
+```
+
+:::

package/docs/startup/start.mdx

@@ -17,4 +17,4 @@ Runs package in the development mode. Applications will be hosted on sequential
 
 The `start` command executes the same steps as the `build` command, then watches for changes and automatically reruns each step as needed.
 
-See [Build Steps](/docs/frontend/uikit/startup/build#build-steps).
+See [Build Steps](./build#build-steps).

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@servicetitan/docs-uikit",
-    "version": "31.6.0",
+    "version": "32.0.1",
     "description": "",
     "repository": {
         "type": "git",
@@ -16,5 +16,5 @@
     "cli": {
         "webpack": false
     },
-    "gitHead": "533bcbd267e11c88700b29f539ca1cb5de6440ae"
+    "gitHead": "2b74dd72d39c2023151699d1cf7a6e6130d64279"
 }