@servicetitan/docs-uikit 32.4.0 → 32.5.0

package/docs/install.mdx

@@ -0,0 +1,171 @@
+---
+title: Installing Dependencies
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+#### [CHANGELOG (@servicetitan/install)](https://github.com/servicetitan/uikit/blob/master/packages/install/CHANGELOG.md)
+
+`@servicetitan/install` is a lightweight wrapper around `npm install` that automatically configures access to private ServiceTitan packages and runs `npm install` with ServiceTitan's standard options. Use it instead of plain `npm install` to guarantee that all packages are installed correctly and any necessary pre- and post-installation steps are performed.
+
+```sh
+npx --yes @servicetitan/install
+```
+
+See [package.json in the example project](https://github.com/search?q=repo%3Aservicetitan%2Ffrontend-example+path%3A**%2Fpackage.json+%5C%22bootstrap%5C%22&type=code) for how to use `install` in an npm script.
+
+:::info
+Previously, we recommended using `npx --yes @servicetitan/startup install` to bootstrap projects.
+But as `@servicetitan/startup` grew more features, it became too large for simple bootstrapping.
+The dedicated `@servicetitan/install` package performs a single task and runs quickly.
+And because it has no runtime dependencies, also eliminates risks from third-party changes.
+:::
+
+## Options
+
+| Option       | Description                                                              |
+| :----------- | :----------------------------------------------------------------------- |
+| `--no-token` | Only install dependencies. Don't configure the npm authentication token. |
+| `--token`    | Only configure the npm authentication token. Don't install dependencies. |
+
+## Configuring NPM Token in Development
+
+In development environments, `@servicetitan/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
+`@servicetitan/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 ST_NPM_READONLY_TOKEN
+
+RUN npm config set --location=project "//registry.npmjs.org/:_authToken=$ST_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-without-install) in projects not using `@servicetitan/install`.
+:::
+
+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=${ST_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:
+      ST_NPM_READONLY_TOKEN: ${{ secrets.ST_NPM_READONLY_TOKEN }}
+```
+
+</TabItem>
+<TabItem value="docker">
+
+```dockerfile
+ARG ST_NPM_READONLY_TOKEN
+
+ENV ST_NPM_READONLY_TOKEN=$ST_NPM_READONLY_TOKEN
+
+RUN npm run build
+```
+
+</TabItem></Tabs>
+
+## How to Configure Development Environment When Not Using Install {#how-to-configure-without-install}
+
+:::note
+These instructions are only for projects using [Option 2](#option-2-use-environment-variable) and that are not using `@servicetitan/install`.
+:::
+
+If your project is [using an environment variable](#option-2-use-environment-variable), and it isn't using `@servicetitan/install`, 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/install@latest --token` 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 `@servicetitan/install` 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 `@servicetitan/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/install",
+    }
+```
+
+:::

package/docs/startup/install.mdx

@@ -2,6 +2,14 @@
 title: install
 ---
 
+:::danger
+The `startup install` command is deprecated; please instead use [@servicetitan/install](../install).
+
+As `@servicetitan/startup` grew more features, it became too large for simple bootstrapping. The
+dedicated `@servicetitan/install` package performs a single task and runs quickly. And because it
+has no runtime dependencies, also eliminates risks from third-party changes.
+:::
+
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 

package/docs/startup/review.mdx

@@ -167,7 +167,7 @@ For example, given:
 }
 ```
 
-It runs:
+It runs
 
 ```sh
 npm pkg set cli.webpack.static.directory="src/public" -w packages/app
@@ -176,6 +176,27 @@ npm pkg delete cli.webpack.contentBase -w packages/app
 
 ---
 
+### no-deprecated-startup-install
+
+Detects when projects use the deprecated `@servicetitan/startup install` bootstrap script.
+
+Previously, we suggested using `npx --yes @servicetitan/startup install` to bootstrap projects.
+But as `@servicetitan/startup` grew more features, it became too large for simple bootstrapping.
+
+The dedicated `@servicetitan/install` package performs a single task and runs quickly.
+And because it has no runtime dependencies, eliminates risks from third‑party changes.
+
+#### ✅ Autofix
+
+This rule supports autofix.
+It changes the bootstrap script to `npx --yes @servicetitan/install`.
+
+It runs
+
+```sh
+npm pkg set scripts.bootstrap="npx --yes @servicetitan/install"
+```
+
 ### no-direct-peer-dependencies
 
 Detects when a package is listed as both a direct dependency and a peer dependency.
@@ -315,7 +336,7 @@ And,
 }
 ```
 
-It runs:
+It runs
 
 ```sh
 npm pkg set "main"="dist/index.js" -w packages/lib
@@ -341,7 +362,7 @@ It adds the missing `react` or `react-dom` dependency, using the same version th
 }
 ```
 
-It runs:
+It runs
 
 ```sh
 npm pkg set dependencies["react-dom"]="^18.3.1"

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@servicetitan/docs-uikit",
-    "version": "32.4.0",
+    "version": "32.5.0",
     "description": "",
     "repository": {
         "type": "git",
@@ -16,5 +16,5 @@
     "cli": {
         "webpack": false
     },
-    "gitHead": "836bcc0dc0859bf1ac0d3c679996e7b753893674"
+    "gitHead": "9ba97491f520e7b5914179aa061d1c3c3285079d"
 }