|
| 1 | +--- |
| 2 | +title: Agentic coding |
| 3 | +category: Contributing |
| 4 | +order: 8 |
| 5 | +--- |
| 6 | + |
| 7 | +# Building Instructure UI |
| 8 | + |
| 9 | +Instructure UI is a mono-repository which means it has multiple packages (almost always a component means an individual package) and they are treated as one whole package when dealing with dependencies and building them. |
| 10 | + |
| 11 | +The project uses `pnpm` for managing these packages and also for resolving dependencies, running scripts and managing the whole mono-repository itself. |
| 12 | + |
| 13 | +> **Note**: Windows is only partially supported. One can build the project and documentation apps, running other commands (like testing) fail. |
| 14 | +> |
| 15 | +> Also we're using environment variables through our build pipeline and they are defined differently in Linux/OSX and Windows. |
| 16 | +
|
| 17 | +### How to build the project |
| 18 | + |
| 19 | +In order to build the project one should have [`git`](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git), [`node`](https://nodejs.org/en/download/) (supported version is defined in the root [package.json](https://github.com/instructure/instructure-ui/blob/master/package.json#L90)), and [`pnpm`](https://pnpm.io/installation) installed. |
| 20 | + |
| 21 | +1. Download the source code and go into the root directory of instructure-ui: |
| 22 | + |
| 23 | + ```sh |
| 24 | + --- |
| 25 | + type: code |
| 26 | + --- |
| 27 | + git clone https://github.com/instructure/instructure-ui.git |
| 28 | + cd instructure-ui |
| 29 | + ``` |
| 30 | + |
| 31 | +2. Install dependencies for packages: |
| 32 | + |
| 33 | + ```sh |
| 34 | + --- |
| 35 | + type: code |
| 36 | + --- |
| 37 | + pnpm install |
| 38 | + ``` |
| 39 | + |
| 40 | +3. Run the bootstrap script: |
| 41 | + |
| 42 | + ```sh |
| 43 | + --- |
| 44 | + type: code |
| 45 | + --- |
| 46 | + pnpm run bootstrap |
| 47 | + ``` |
| 48 | + |
| 49 | + This script will invoke: |
| 50 | + |
| 51 | + - the `TypeScript` compiler (tsc) to generate the type definitions for the packages |
| 52 | + - `babel` to transpile the source code of every package to a version that browsers can understand (supported browsers are defined in [`@instructure/browserslist-config-instui`](https://github.com/instructure/instructure-ui/blob/master/packages/browserslist-config-instui/index.js) package) |
| 53 | + - a `clean` script which removes any previous build output |
| 54 | + |
| 55 | +The output of bootstrap can be found in `lib`, `es` (for non node packages) and `types` directories for each package respectively, where: |
| 56 | + |
| 57 | +- `lib` contains [`commonjs`](https://nodejs.org/docs/latest/api/modules.html#modules-commonjs-modules) module output |
| 58 | +- `es` contains [`es`](https://nodejs.org/docs/latest/api/esm.html#modules-ecmascript-modules) module output |
| 59 | +- `types` contains the TypeScript type definitions |
| 60 | + |
| 61 | +That is all, if you are interested about the available commands check out the [Dev Commands Cheat Sheet](#dev-commands-cheat-sheet) section below. |
| 62 | + |
| 63 | +### How to build the documentation |
| 64 | + |
| 65 | +This assumes that all of the above mentioned steps are completed, meaning the project dependencies are installed and the project itself is built. |
| 66 | + |
| 67 | +The documentation application is a simple client side only single page application (SPA) built with `React`. It uses Instructure UI components itself. |
| 68 | + |
| 69 | +In order to build the static files for the documentation, from the project root run: |
| 70 | + |
| 71 | +```sh |
| 72 | +--- |
| 73 | +type: code |
| 74 | +--- |
| 75 | +pnpm run build:docs |
| 76 | +``` |
| 77 | + |
| 78 | +This should create the static bundle using `webpack`, the output files can be found in `instructure-ui/packages/__docs__/__build__/`. |
| 79 | + |
| 80 | +We use this bundle to host the documentation at [instructure.design](https://instructure.design). |
| 81 | + |
| 82 | +## AI Coding Assistant Setup |
| 83 | + |
| 84 | +### Using Claude Code |
| 85 | + |
| 86 | +For comprehensive guidance on using Claude Code with this repository, see [CLAUDE.md](https://github.com/instructure/instructure-ui/blob/master/CLAUDE.md) in the repository root. |
| 87 | + |
| 88 | +## Generating AI agent friendly markdown files for components and guides |
| 89 | + |
| 90 | +InstUI's JSON metadata is used to create a markdown version of the documentation for easier use by AI tools and coding assistants. |
| 91 | + |
| 92 | +These markdown files are created during the build process then are made available for users using specific links. |
| 93 | + |
| 94 | +This collection includes structured files for almost everything under the 'Getting Started', 'Guides', 'Patterns' and 'Components' (including Components/AI Components and Components/Utilities) sections of the documentation. |
| 95 | + |
| 96 | +How it works: |
| 97 | +The core logic resides in `packages/__docs__/buildScripts/ai-accessible-documentation/generate-ai-accessible-markdowns.mts`. |
| 98 | + |
| 99 | +1. **Input and output** |
| 100 | + Input: The script processes the JSON files found under `packages/__docs__/__build__/docs` if they belong to the corresponding sections mentioned above. |
| 101 | + Output: A directory of generated .md files under `packages/__docs__/__build__/markdowns`, which are also compressed into a documentation.zip archive as well which also can be found in this directory. |
| 102 | + |
| 103 | +2. **Data loading and classification** |
| 104 | + The script reads all JSON files from the specified docs folder. |
| 105 | + Identifies the necessary components and guides based on having props (components) or having a `relevantForAI: true` YAML flag (guides). |
| 106 | + |
| 107 | +3. **Markdown generation** |
| 108 | + A markdown file is generated using the data found under the 'description' key. As for components, an addtional table of props and a 'Usage' section is generated for showing how to import the component. |
| 109 | + As for the table of props, the props of a child component (e.g. Tabs.Panel) of a parent component (e.g. Tabs) is also included in the table. |
| 110 | + |
| 111 | +4. **Index file creation and packaging** |
| 112 | + After all individual markdown files are written, index.md file is generated, which acts as a master list of contents for the entire documentation set. |
| 113 | + Finally, the script uses the system's zip command to package all .md files in the output directory into the final documentation.zip file, which can be downloaded here: https://instructure.design/markdowns/documentation.zip |
| 114 | + The AI-friendly markdown files are now avaliable either downloading the documentation.zip file or through a link that follows this pattern: https://instructure.design/markdowns/Alert.md |
| 115 | + |
| 116 | +## Generating llms.txt for LLMs |
| 117 | + |
| 118 | +In addition to the markdown files, a llms.txt file is also generated. This file is specifically formatted for optimal consumption by Large Language Models (LLMs) and AI coding agents. |
| 119 | +This file contains a catalog of links pointing to the online markdown files of InstUI components and guides generated above and short description of each component/guide |
| 120 | + |
| 121 | +How it works: |
| 122 | +The core logic resides in `packages/__docs__/buildScripts/ai-accessible-documentation/ggenerate-ai-accessible-llms-file.mts`. |
| 123 | + |
| 124 | +1. **Input and output** |
| 125 | + Input: The script processes the following JSON file: `packages/__docs__/__build__/markdown-and-sources-data.json` |
| 126 | + Output: An llms.txt file is placed into `packages/__docs__/__build__` which can be found here: https://instructure.design/llms.txt |
| 127 | + |
| 128 | +2. **Data loading and classification** |
| 129 | + The script indenftifies the necessary elements looking for "Getting Started", "Guides", "Patterns", and "Components" section names. |
| 130 | + |
| 131 | +3. **Markdown generation** |
| 132 | + It creates a documentation structure like this: |
| 133 | + |
| 134 | + ```md |
| 135 | + --- |
| 136 | + type: code |
| 137 | + --- |
| 138 | + |
| 139 | + # Instructure UI (InstUI) - React Component Library |
| 140 | + |
| 141 | + ## Documentation |
| 142 | + |
| 143 | + ### User Guides |
| 144 | + |
| 145 | + #### Getting Started |
| 146 | + |
| 147 | + #### Guides |
| 148 | + |
| 149 | + #### Patterns |
| 150 | + |
| 151 | + ### Components |
| 152 | + |
| 153 | + #### Utilities |
| 154 | + |
| 155 | + #### AI components |
| 156 | + ``` |
| 157 | + |
| 158 | + It generates links for the components/guides and appends a brief summary of each of them using the `packages/__docs__/buildScripts/ai-accessible-documentation/summaries-for-llms-file.json` file, searching for matching component/guide title. |
| 159 | + |
| 160 | +## Dev Commands Cheat Sheet |
| 161 | + |
| 162 | +This is a quick developer reference for common Instructure UI repository commands. All should be run from the repository root. Make sure you run `pnpm install` first, as many of these commands will require you to have `lerna` dependencies installed before they will work. |
| 163 | + |
| 164 | +| Command | Description | |
| 165 | +| ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |
| 166 | +| `pnpm run bootstrap` | Clean all node modules and build output, reinstall dependencies, create fresh build including regenerating design tokens and type declaration files. | |
| 167 | +| `pnpm run dev` | Run a local instance of the documentation app in dev mode. Docs will be served at `http://0.0.0.0:9090`. Port can be specified too e.g. `pnpm run dev -- -p 1234` | |
| 168 | +| `pnpm run start` | Run a local instance of the documentation app in production mode. The urls where the docs are being served will be included in the output of this command. | |
| 169 | +| `pnpm run build` | Run the build command for all Instructure UI packages. Similar to bootstrap, but without the cleaning steps, installation of dependencies, and without the token and type generation. | |
| 170 | +| `pnpm run build:watch` | Identical to `pnpm run build` but will watch for changes. Note: this command is rarely necessary to use. If you are running `pnpm run dev`, the docs app will already be watching for any changes for components. | |
| 171 | +| `pnpm run build -- --scope <package-name>` | Identical to `pnpm run build` but scoped to a single package. For example, to run the command only for the `ui-badge` package, you would do `pnpm run build -- --scope @instructure/ui-badge` | |
| 172 | +| `pnpm run build:watch -- --scope <package-name>` | Identical to `pnpm run build:watch` but scoped to a single package. For example, to run the command only for the `ui-badge` package, you would do `pnpm run build:watch -- --scope @instructure/ui-badge` | |
| 173 | +| `pnpm run build:ts` | Create type declaration files using `tsc` (TypeScript compiler). | |
| 174 | +| `pnpm run test:vitest` | Run all Instructure UI component-level unit tests in a jsdom environment. | |
| 175 | +| `pnpm run test:vitest-watch [ComponentName]` | Run all tests of the selected component in wach mode. | |
| 176 | +| `pnpm run cy:component` | Run all Instructure UI component-level Cypress tests in a real browser environment. | |
| 177 | +| `pnpm run cy:component -- --spec "cypress/component/[ComponentName].cy.tsx"` | Run specific component test file. | |
0 commit comments