|
1 | | -> [!WARNING] |
2 | | -> Commits to `main` trigger builds & deploys to [instructure.ai](https://instructure.ai/). Use pull requests to update packages. |
| 1 | +# instructure.ai |
3 | 2 |
|
4 | | -# @instructure.ai/shared-configs |
| 3 | +This is a monorepo of apps and packages. Apps are served on the [instructure.ai](https://instructure.ai) website and packages are released to the [instructure.ai](https://www.npmjs.com/org/instructure.ai) NPM organization. |
5 | 4 |
|
6 | | -   |
| 5 | +Configs and dev dependencies are shared from the root package `@instructure.ai/shared-configs` and extended in workspace packages in `/apps` and `/packages`. |
7 | 6 |
|
8 | 7 |
|
9 | | -This is a monorepo of apps and packages. Apps are served on [instructure.ai](https://instructure.ai) |
| 8 | +## @instructure.ai/shared-configs |
10 | 9 |
|
11 | | -Configs and dev dependencies are shared from the root package `@instructure.ai/shared-configs` and extended in workspace packages in `/apps` and `/packages`. |
| 10 | +    |
| 11 | + |
| 12 | +`@instructure.ai/shared-configs` is the root package of this monorepo and provides package templates, workspace utilities, and base configurations. |
| 13 | + |
| 14 | +### Package Templates |
12 | 15 |
|
13 | | -Helper utilities are provided for adding and managing packages. |
| 16 | +Package templates are provided for apps and packages and can be instantiated with the Workspace script `new`. |
14 | 17 |
|
15 | 18 | ```shell |
16 | 19 | pnpm new <packagename> [--template (default: vanilla | react | instui | esm)] |
17 | 20 | ``` |
18 | 21 |
|
19 | | -Will instantiate a new vanillajs or react project with all configurations set up under `./<apps|packages>/<packagename>` |
| 22 | +### Workspace Utilities |
20 | 23 |
|
21 | | -pnpm scripts allow specifying a package name, or omitting it (if available) to recursively execute. |
| 24 | +In addition to pnpm builtins, the `workspace` script provides an interface for interacting with multiple packages at once. |
22 | 25 |
|
23 | 26 | ```shell |
24 | | -pnpm build [<packagename>] |
25 | | -pnpm dev <packagename> |
26 | | -pnpm preview <packagename> |
27 | | -pnpm lint [<packagename>] |
| 27 | +pnpm build <option> [args] |
| 28 | +pnpm dev <packagename> [args] |
| 29 | +pnpm preview <packagename> [args] |
| 30 | +pnpm release <option> [args] |
| 31 | +pnpm lint <option> [args] |
| 32 | +pnpm test <option> [args] |
| 33 | +pnpm workspace [info] |
28 | 34 | ``` |
29 | 35 |
|
30 | | -The `workspace` script exposes various helpers to make managing multiple packages or apps easier. Options are: |
| 36 | +Global `option`s provided by `workspace` are: |
31 | 37 |
|
32 | 38 | * all |
33 | | -* packages |
34 | 39 | * apps |
| 40 | +* packages |
35 | 41 | * root |
36 | | -* package <name> |
37 | | -* app <name> |
38 | | -* <name> |
39 | | - |
40 | | -So you can run `pnpm lint apps && pnpm build apps` without touching `/packages` or the Workspace root. |
41 | | - |
42 | | -What comes out of the box? |
43 | | - |
44 | | -* vite (vanilla-ts, react-ts) |
45 | | -* vite-node |
46 | | -* vite-plugin-dts |
47 | | -* vitest |
48 | | -* biomejs |
49 | | -* typescript-native |
50 | | -* dotenvx |
51 | | -* github publishing |
52 | | -* vscode settings |
53 | | -* shared public assets |
54 | | -* github copilot instructions |
| 42 | +* app `<name>` |
| 43 | +* package `<name>` |
| 44 | +* `<name>` |
| 45 | + |
| 46 | +Though individual scripts may only support a subset of options, and will throw an error when an unsupported option is passed. Any args can be passed and will be used against each package in the options list. |
| 47 | + |
| 48 | +```shell |
| 49 | +# lint & build apps |
| 50 | +# passes the `write` flag to `biome check` |
| 51 | + |
| 52 | +pnpm lint apps --write && pnpm build apps |
| 53 | +``` |
| 54 | + |
| 55 | +Package names can be passed with or without the workspace prefix. `pnpm release @instructure.ai/aiinfo` is the same as `pnpm release aiinfo`. |
| 56 | + |
| 57 | +### Base Configurations |
| 58 | + |
| 59 | +Configuration files are provided and where possible use inheritance. There are also some devex hints provided. |
| 60 | + |
| 61 | +#### Dev Experience |
| 62 | + |
| 63 | +* Recommended vscode plugins will be prompted when this repo is opened `./vscode/extensions.json` |
| 64 | +* VScode project settings for things like lint-on-save `./vscode/settings.json` |
| 65 | +* Github copilot instructions when using an [instui](https://instructure.design/) package `./template/instui/.github/copilot-instructions.md` |
| 66 | + |
| 67 | +#### Vite |
| 68 | + |
| 69 | +Vite uses shared configs to provide a baseline setup for each package. Settings can be overwritten using [mergeConfig](https://vite.dev/guide/api-javascript.html#mergeconfig). |
| 70 | +`mergeConfig(baseconfig, {...opts})` |
| 71 | + |
| 72 | +```shell |
| 73 | +📁 / |
| 74 | + ├── 📄 vite.config.mts # Base config for apps |
| 75 | + ├── 📄 vite.config.esm.mts # Base config for packages |
| 76 | + ├── 📄 vite.config.react.mts # Merges ./vite.config.mts |
| 77 | + ├── 📂 apps/ |
| 78 | + │ └── 📂 roadmap/ |
| 79 | + │ └── vite.config.mts # Merges ./vite.config.react.mts |
| 80 | + └── 📂 /packages |
| 81 | + └── 📂 aiinfo/ |
| 82 | + └── vite.config.mts # Merges ./vite.config.esm |
| 83 | +``` |
| 84 | + |
| 85 | +#### Typescript |
| 86 | + |
| 87 | +> [!NOTE] |
| 88 | +> This project uses the experimental [@typescript/native-preview](https://www.npmjs.com/package/@typescript/native-preview) |
| 89 | +
|
| 90 | +Typescript uses shared configs to provide a baseline setup for each package. Settings can be overwritten by re-declaring them in the package's `tsconfig.json`. See [tsconfig extends](https://www.typescriptlang.org/tsconfig/#extends). |
| 91 | + |
| 92 | +```shell |
| 93 | +📁 / |
| 94 | + ├── 📄 tsconfig.json # Base config for apps |
| 95 | + ├── 📄 tsconfig.node.json # Extends ./tsconfig.json |
| 96 | + ├── 📂 apps/ |
| 97 | + │ └── 📂 roadmap/ |
| 98 | + │ └── tsconfig.json # Extends ./tsconfig.node.json |
| 99 | + └── 📂 /packages |
| 100 | + └── 📂 aiinfo/ |
| 101 | + └── tsconfig.json # Extends ./tsconfig.json |
| 102 | +``` |
| 103 | + |
| 104 | +#### Vitest |
| 105 | + |
| 106 | +Vitest uses shared configs to provide a baseline setup for each package. Settings can be overwritten using [mergeConfig](https://vitest.dev/config/). |
| 107 | +`mergeConfig(baseconfig, {...opts})` |
| 108 | + |
| 109 | +```shell |
| 110 | +📁 / |
| 111 | + ├── 📄 vitest.config.shared.mts # Base config |
| 112 | + ├── 📄 vitest.config.mts # Merges ./vitest.config.shared.mts (workspace root config) |
| 113 | + ├── 📂 apps/ |
| 114 | + │ └── 📂 roadmap/ |
| 115 | + │ └── vitest.config.mts # Merges ./vitest.config.shared.mts |
| 116 | + └── 📂 /packages |
| 117 | + └── 📂 aiinfo/ |
| 118 | + └── vite.config.mts # Merges ./vitest.config.shared.mts |
| 119 | +``` |
| 120 | + |
| 121 | +Vitest uses istanbul to provide coverage for non-v8 (hi firefox 👋) testing. A custom reporter is included that outputs basic rollup stats in `./coverage/coverage.yml`. |
| 122 | + |
| 123 | +#### Biome |
| 124 | + |
| 125 | +Biome is **not** configured to use a root config, each package's config is a standalone copy from its template folder. |
| 126 | + |
| 127 | +```shell |
| 128 | +📁 / |
| 129 | + ├── 📄 biome.jsonc # Copy of ./template/shared/biome.jsonc (workspace root config) |
| 130 | + ├── 📂 .template/ |
| 131 | + │ └── 📂 shared/ |
| 132 | + │ └── biome.jsonc # Base config |
| 133 | + └── 📂 /apps |
| 134 | + │ └── 📂 roadmap/ |
| 135 | + │ └── biome.jsonc # Copy of ./template/shared/biome.jsonc |
| 136 | + └── 📂 /packages |
| 137 | + └── 📂 aiinfo/ |
| 138 | + └── biome.jsonc # Copy of ./template/shared/biome.jsonc |
| 139 | +``` |
| 140 | + |
| 141 | +#### Package.json |
| 142 | + |
| 143 | +The root workspace package.json defines workspace exports and shares workspace `devDependencies`. |
| 144 | + |
| 145 | +```shell |
| 146 | +📁 / |
| 147 | + ├── 📄 package.json # Base config (workspace root config) |
| 148 | + └── 📂 /apps |
| 149 | + │ └── 📂 roadmap/ |
| 150 | + │ └── package.json # Imports ./package.json |
| 151 | + └── 📂 /packages |
| 152 | + └── 📂 aiinfo/ |
| 153 | + └── package.json # Imports ./package.json |
| 154 | +``` |
| 155 | + |
| 156 | +##### devDependencies |
| 157 | + |
| 158 | +The following `devDependencies` are provided. No `dependencies` are included. |
| 159 | + |
| 160 | +```json |
| 161 | +"devDependencies": { |
| 162 | + "@biomejs/biome": "latest", |
| 163 | + "@instructure/browserslist-config-instui": "^11", |
| 164 | + "@types/react": "latest", |
| 165 | + "@types/react-dom": "latest", |
| 166 | + "@typescript/native-preview": "latest", |
| 167 | + "@vitejs/plugin-react": "latest", |
| 168 | + "@vitest/coverage-istanbul": "latest", |
| 169 | + "@vitest/coverage-v8": "latest", |
| 170 | + "babel-plugin-react-compiler": "latest", |
| 171 | + "browserslist": "latest", |
| 172 | + "istanbul-lib-report": "latest", |
| 173 | + "istanbul-reports": "latest", |
| 174 | + "lightningcss": "latest", |
| 175 | + "react-compiler-runtime": "^latest", |
| 176 | + "terser": "latest", |
| 177 | + "vite": "latest", |
| 178 | + "vite-node": "latest", |
| 179 | + "vite-plugin-dts": "latest", |
| 180 | + "vitest": "latest", |
| 181 | + "yaml": "latest" |
| 182 | + }, |
| 183 | +``` |
| 184 | + |
| 185 | +In workspace packages they are imported with: |
| 186 | + |
| 187 | +``` |
| 188 | + "devDependencies": { |
| 189 | + "@instructure.ai/shared-configs": "workspace:^" |
| 190 | + } |
| 191 | +``` |
| 192 | + |
| 193 | +This import is included in the template when using the workspace script `new`. |
0 commit comments