@servicetitan/docs-uikit 30.3.0 → 31.0.0

package/docs/startup/review.mdx

@@ -0,0 +1,373 @@
+---
+title: review
+---
+
+The `startup review` command is a static analysis tool for monorepos using `@servicetitan/startup`.
+It checks your workspace for common configuration and dependency issues using a set of pluggable rules.
+This helps maintain consistency, avoid dependency hell, and enforce best practices across all packages in your repository.
+
+## Usage
+
+```sh
+npx startup review
+```
+
+- Run from the root of your workspace (where your root `package.json` and `package-lock.json` are located).
+- The command will scan all packages (as defined by your workspace configuration) and report any errors or warnings found by the enabled rules.
+
+---
+
+## How It Works
+
+1. **Workspace Discovery**: Finds all packages in your monorepo using your workspace configuration.
+2. **Dependency Analysis**: Builds a dependency graph and collects all installed versions from `package-lock.json`.
+3. **Rule Execution**: Runs each enabled rule against your project and packages.
+4. **Reporting**: Outputs a summary of all problems found, grouped by file and severity.
+
+---
+
+## Output
+
+- Errors and warnings are grouped by location.
+- The summary includes the total number of problems, broken down by severity.
+- Errors will cause the command to exit with a non-zero status.
+
+---
+
+## Troubleshooting
+
+- Make sure you run the command from the workspace root.
+- If you see unexpected results, check your configuration and ensure your `package-lock.json` is up to date.
+
+---
+
+## Options
+
+### --fix
+
+You can run `startup review` with the `--fix` flag to automatically fix certain problems detected by enabled rules.
+
+```sh
+npx startup review --fix
+```
+
+- When `--fix` is provided, rules that support autofix will attempt to update your configuration, as needed.
+- Not all rules support autofix. For those that do, the documentation indicates what is fixable.
+- When `--fix` is used with [`--rule`](#--rule), only the specified rules are fixed.
+
+#### "Highest" versions
+
+When fixing conflicting versions (see for example [require-one-package-version](#require-one-package-version))
+`--fix` selects the semver string with the highest possible matching version.
+If there's a tie, it picks the one with the higher lowest possible matching version.
+
+For example,
+
+- `^1.0.0` is higher than `~1.0.0`
+- `>=2` is higher than `>=1`, because `>=2` has a higher lowest version
+
+### --rule
+
+Run `startup review` with the `--rule` flag to limit its checks to one or more rules.
+
+```sh
+npx startup review --rule require-project-version-in-root-node-modules
+```
+
+- Use `--rule` multiple times to limit checks to the specified rules.
+- When `--rule` is used with [`--fix`](#--fix), only the specified rules are fixed.
+
+---
+
+## Configuration
+
+By default, all rules enabled with a pre-defined severity.
+You can customize the behavior and configure which rules are enabled, their severity, and rule-specific options in your root `package.json`.
+
+### Example Configuration in root `package.json`
+
+```json
+{
+    "cli": {
+        "review": {
+            "rules": {
+                "no-typescript-entry-point": "warn",
+                "require-explicit-side-effects": ["error", { "exclude": ["utils"] }],
+                "require-one-anvil-uikit-contrib-version": "warn",
+                "require-npmrc": "off"
+            }
+        }
+    }
+}
+```
+
+Rules accept a lone severity level, or an array `[level, options]` with rule-specific options.
+
+### Severity levels
+
+| Level     | Description                                             |
+| :-------- | :------------------------------------------------------ |
+| `"error"` | Treat violations as errors (fail the command).          |
+| `"warn"`  | Treat violations as warnings (do not fail the command). |
+| `"off"`   | Disable the rule.                                       |
+
+:::tip
+Use `"off"` to temporarily disable a rule, or `"warn"` to see issues without failing your CI.
+:::
+
+### Options
+
+#### `exclude`
+
+Array of package names to exclude from the check.
+For example, this configuration allows `@servicetitan/datetime-utils` to have a
+different version from other `anvil-uikit-contrib` packages.
+
+```json
+"require-one-anvil-uikit-contrib-version": [
+    "error",
+    { "exclude": ["@servicetitan/datetime-utils"] }
+]
+```
+
+And, this configuration requires all libraries except `utils` to have explicit `sideEffects`.
+
+```json
+"require-explicit-side-effects": ["error", { "exclude": ["utils"] }],
+```
+
+---
+
+## Rules
+
+### no-typescript-entry-point
+
+Ensures that no package uses a TypeScript file as its main entry point or in its `exports`.
+
+Because `startup` compiles and builds in separate steps, packages should export
+the compiled Javascript output instead of the TypeScript source files. For example,
+
+```json title="package.json"
+{
+    "main": "./dist/index.js",
+    "typings": "./dist/index.d.ts"
+}
+```
+
+:::note
+The Webpack documentation suggests using a configuration that directs webpack to
+enter through `./src/index.ts` and load all `.ts` and `.tsx` files through `ts-loader`.
+However, because `startup` precompiles Typescript files, this is redundant and
+webpack should be configured to load the compiled Javascript.
+:::
+
+#### ✅ Autofix
+
+This rule supports autofix.
+It changes the Typescript entry point to the corresponding `.js` file
+in the package's output folder. For example, given:
+
+```json title="packages/lib/package.json"
+{
+    "main": "src/index.ts"
+}
+```
+
+And,
+
+```json title="packages/lib/tsconfig.json"
+{
+    "compilerOptions": {
+        "rootDir": "src",
+        "outDir": "dist"
+    }
+}
+```
+
+It runs:
+
+```sh
+npm pkg set "main"="dist/index.js" -w packages/lib
+```
+
+---
+
+### require-explicit-side-effects
+
+Warns if a package is missing the `sideEffects` property in its `package.json`.
+
+Including the `sideEffects` property in a package’s `package.json` is important for the following reasons:
+
+- **Tree-shaking Optimization**  
+  The `sideEffects` property tells bundlers (like Webpack) which files in your package are "pure" (i.e., have no side effects when imported). This allows bundlers to safely remove unused code during the build process, resulting in smaller bundle sizes and faster load times.
+
+- **Preventing Broken Code**  
+  If your package does have files with side effects (such as polyfills, global CSS imports, or code that modifies global state), you can explicitly list them in the `sideEffects` array. This ensures that bundlers do not accidentally remove these files, which could otherwise break your application.
+
+- **Best Practice for Libraries**  
+  For libraries, explicitly setting `"sideEffects": false` (if your package is side-effect free) or providing an array of files with side effects is considered a best practice. It signals to consumers and tools that your package is optimized for modern build workflows.
+
+    **Example**
+
+    ```json
+    { "sideEffects": false }
+    ```
+
+    Or, if only some files have side effects:
+
+    ```json
+    {
+        "sideEffects": ["./src/polyfills.js", "./src/styles/global.css"]
+    }
+    ```
+
+#### ❌ Autofix
+
+This rule is not fixable automatically.
+You must determine whether any files in the package have side effects and manually add the appropriate `sideEffects` property. E.g.,
+
+```sh
+npm pkg set sideEffects=false -w @servicetitan/package
+```
+
+---
+
+### require-npmrc
+
+Checks that your project contains a `.npmrc` file with `legacy-peer-deps=true`.
+
+```text title=".npmrc"
+legacy-peer-deps=true
+```
+
+Setting `legacy-peer-deps=true` tells npm to use the older, more permissive peer dependency resolution algorithm (as in npm v6). This can help avoid installation failures when packages in your dependency tree have conflicting or unmet peer dependencies, which is common in large monorepos or when using older packages.
+
+#### ✅ Autofix
+
+This rule supports autofix.
+It creates or updates your `.npmrc` file to include `legacy-peer-deps=true`. E.g.,
+
+```sh
+npm config set --location=project legacy-peer-deps=true
+```
+
+---
+
+### require-one-anvil-uikit-contrib-version
+
+Ensures the same version of related `anvil-uikit-contrib` packages is installed across the workspace.
+
+Different versions of related `anvil-uikit-contrib` packages may have breaking changes or incompatible APIs. If some packages use an older version while others use a newer one, you may encounter runtime errors, unexpected behavior, or subtle bugs that are difficult to diagnose.
+
+Having the same version of each `anvil-uikit-contrib` package also reduces the risk of dependency duplication, which can bloat your `node_modules` and increase build times.
+
+#### ✅ Autofix
+
+This rule supports autofix.
+It sets all related `anvil-uikit-contrib` packages to the most common version in the repo.
+If multiple versions tie for the most common, it uses the [highest](#highest-versions) version among the top contenders.
+
+---
+
+### require-one-package-version
+
+Ensures that your project directly depends on only one version of each dependency.
+This is important because:
+
+- **Avoids Conflicts and Bugs**  
+  Multiple versions of the same package can lead to subtle bugs, type mismatches, and unpredictable behavior, especially if different parts of your codebase expect different versions of the same API.
+
+- **Reduces Bundle Size**  
+  Having only one version of a package prevents duplication in your `node_modules` and in your production bundles, resulting in smaller, faster builds.
+
+- **Simplifies Dependency Management**  
+  Upgrading, debugging, and maintaining dependencies is much easier when there is only one version to track and update.
+
+#### ✅ Autofix
+
+This rule supports autofix.
+It sets the version of each dependency to the [highest](#highest-versions) of the conflicting versions.
+
+---
+
+### require-one-uikit-version
+
+Ensures the same version of related `uikit` packages is installed across the workspace.
+
+Different versions of related `uikit` packages may have breaking changes or incompatible APIs. If some packages use an older version while others use a newer one, you may encounter runtime errors, unexpected behavior, or subtle bugs that are difficult to diagnose.
+
+Having the same version of each `uikit` package also reduces the risk of dependency duplication, which can bloat your `node_modules` and increase build times.
+
+#### ✅ Autofix
+
+This rule supports autofix.
+It sets all related `uikit` packages to the most common version in the repo.
+If multiple versions tie for the most common, it uses the [highest](#highest-versions) version among the top contenders.
+
+---
+
+### require-project-version-in-root-node-modules
+
+Checks that, when multiple versions of a dependency are installed, the version in the root `node_modules` matches one of the versions used by your project.
+
+If the root `node_modules` contains a version that is not referenced anywhere in your project, some packages may accidentally import the wrong version, leading to subtle bugs, type mismatches, or runtime errors.
+
+#### ✅ Autofix
+
+This rule supports autofix.
+It hoists the version that the project directly depends on to the root `node_modules`.
+If the project depends directly on multiple versions of a package, it hoists the [highest](#highest-versions) version.
+
+#### How to fix manually
+
+To manually hoist packages to the root `node_modules`:
+
+1. Add the package(s) to the root `package.json`. E.g.,
+
+    ```sh
+    npm pkg set dependencies[<name>]=<version>
+    ```
+
+    Where `<name>` is the package name and `<version>` is the package version to hoist.
+
+2. Update the `package-lock.json`:
+
+    ```sh
+    npm install --legacy-peer-deps --package-lock-only --prefer-dedupe
+    ```
+
+3. Remove the package(s) from the root `package.json`. E.g.,
+
+    ```sh
+    npm pkg delete dependencies[<name>]
+    ```
+
+4. Update `package-lock.json` a final time:
+
+    ```sh
+    npm install --legacy-peer-deps --package-lock-only --prefer-dedupe
+    ```
+
+---
+
+### require-servicetitan-scope
+
+Checks that public packages are scoped to the `@servicetitan` namespace.
+This is important because:
+
+- **Avoids Naming Conflicts**  
+  Scoping ensures ServiceTitan package names are unique within the npm ecosystem, preventing accidental clashes with public or third-party packages.
+
+- **Improves Security**  
+  Using a scoped namespace helps prevent dependency confusion attacks, where malicious actors publish packages with the same name as ServiceTitan internal packages.
+
+- **Enables Scoped Publishing and Access Control**  
+  ServiceTitan can control access, permissions, and publishing rights at the scope level, making it easier to manage private and public packages.
+
+#### ❌ Autofix
+
+This rule is not fixable automatically.
+
+- If the package is private and not published to NPM, add `private: true` to its `package.json`.
+- If the package is published to NPM, you must manually change the package name and update affected documentation, applications and workflows
+  to use the new name.

package/docs/startup/start.mdx

@@ -0,0 +1,18 @@
+---
+title: start
+---
+
+Runs package in the development mode. Applications will be hosted on sequential free ports starting from 8080. Pages will automatically reload on changes to the code.
+
+#### Arguments
+
+- `--scope <glob>` - Include only packages with names matching the given glob.
+- `--ignore <glob>` - Exclude packages with names matching the given glob.
+- `--code-coverage` - Add [instrumentation](https://github.com/JS-DevTools/coverage-istanbul-loader) to bundled code in order to collect code coverage
+- `--use-tsc` - Use TSC for TypeScript compilation
+
+## Start steps
+
+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/startup/build#build-steps).