|
1 | | -# Build & Run Guide |
2 | | - |
3 | | -This repository contains the React component library, a demo app, and the MkDocs documentation site. |
4 | | -Use this guide to set up a local workstation and verify changes before publishing. |
5 | | - |
6 | | -## 1. Prerequisites |
7 | | - |
8 | | -- Node.js 18+ and npm 10+ |
9 | | -- For the documentation site: Python 3.9+ with `pip` |
10 | | - |
11 | | -## 2. Install Dependencies |
12 | | - |
13 | | -```bash |
14 | | -npm install |
15 | | -``` |
16 | | - |
17 | | -This installs all workspace packages, including the demo app dependencies. |
18 | | - |
19 | | -## 3. Build the Library |
20 | | - |
21 | | -```bash |
22 | | -npm run build |
23 | | -``` |
24 | | - |
25 | | -- Runs `microbundle-crl` to build the component library |
26 | | -- Outputs the distributable package under `dist/` |
27 | | -- Add `npm run start` to watch for changes during development |
28 | | - |
29 | | -## 4. Run Quality Gates |
30 | | - |
31 | | -- **Unit tests:** `npm run test` |
32 | | -- **Linting:** `npm run lint` |
33 | | - |
34 | | -These should be clean before submitting changes or publishing. |
35 | | - |
36 | | -## 5. Run the Demo Application |
37 | | - |
38 | | -The demo showcases three interactive examples: |
39 | | - |
40 | | -1. **Address Form** – Complete address collection workflow |
41 | | -2. **Events Showcase** – Real-time event logger with all 14 events |
42 | | -3. **Playground** – Test all configuration options |
43 | | - |
44 | | -### Steps: |
45 | | - |
46 | | -1. Update the API key in `example/src/config.js`. The checked-in key is for demos only and may be throttled. |
47 | | -2. Start the dev server: |
48 | | - ```bash |
49 | | - cd example |
50 | | - npm install |
51 | | - npm start # serves the demo on http://localhost:3000 |
52 | | - ``` |
53 | | -3. The demo watches both the library and app; rebuilding the library will refresh the demo automatically. |
54 | | - |
55 | | -## 6. Preview / Build the Documentation Site |
56 | | - |
57 | | -The docs live under `docs-site/` and use MkDocs Material. |
58 | | - |
59 | | -```bash |
60 | | -cd docs-site |
61 | | - |
62 | | -# Create virtual environment (first time only) |
63 | | -python3 -m venv venv |
64 | | - |
65 | | -# Activate virtual environment |
66 | | -source venv/bin/activate # On Windows: venv\Scripts\activate |
67 | | - |
68 | | -# Install dependencies |
69 | | -pip install -r requirements.txt |
70 | | - |
71 | | -# Live preview at http://127.0.0.1:8000 |
72 | | -mkdocs serve |
73 | | - |
74 | | -# Or build static site into site/ directory |
75 | | -mkdocs build |
76 | | -``` |
77 | | - |
78 | | -## 7. Publishing |
79 | | - |
80 | | -### Library |
81 | | - |
82 | | -1. Ensure `npm run build` output is up to date |
83 | | -2. Update version in `package.json` if needed |
84 | | -3. From the repo root: |
85 | | - ```bash |
86 | | - npm publish --access public |
87 | | - ``` |
| 1 | +# Build & Run Guide |
| 2 | + |
| 3 | +This repository contains the React component library, a demo app, and the MkDocs documentation site. |
| 4 | +Use this guide to set up a local workstation and verify changes before publishing. |
| 5 | + |
| 6 | +## 1. Prerequisites |
| 7 | + |
| 8 | +- Node.js 18+ and npm 10+ |
| 9 | +- For the documentation site: Python 3.9+ with `pip` |
| 10 | + |
| 11 | +## 2. Install Dependencies |
| 12 | + |
| 13 | +```bash |
| 14 | +npm install |
| 15 | +``` |
| 16 | + |
| 17 | +This installs all workspace packages, including the demo app dependencies. |
| 18 | + |
| 19 | +## 3. Build the Library |
| 20 | + |
| 21 | +```bash |
| 22 | +npm run build |
| 23 | +``` |
| 24 | + |
| 25 | +- Runs `microbundle-crl` to build the component library |
| 26 | +- Outputs the distributable package under `dist/` |
| 27 | +- Add `npm run start` to watch for changes during development |
| 28 | + |
| 29 | +## 4. Run Quality Gates |
| 30 | + |
| 31 | +- **Unit tests:** `npm run test` |
| 32 | +- **Linting:** `npm run lint` |
| 33 | + |
| 34 | +These should be clean before submitting changes or publishing. |
| 35 | + |
| 36 | +## 5. Run the Demo Application |
| 37 | + |
| 38 | +The demo showcases three interactive examples: |
| 39 | + |
| 40 | +1. **Address Form** – Complete address collection workflow |
| 41 | +2. **Events Showcase** – Real-time event logger with all 14 events |
| 42 | +3. **Playground** – Test all configuration options |
| 43 | + |
| 44 | +### Steps: |
| 45 | + |
| 46 | +1. Update the API key in `example/src/config.js`. The checked-in key is for demos only and may be throttled. |
| 47 | +2. Start the dev server: |
| 48 | + ```bash |
| 49 | + cd example |
| 50 | + npm install |
| 51 | + npm start # serves the demo on http://localhost:3000 |
| 52 | + ``` |
| 53 | +3. The demo watches both the library and app; rebuilding the library will refresh the demo automatically. |
| 54 | + |
| 55 | +## 6. Preview / Build the Documentation Site |
| 56 | + |
| 57 | +The docs live under `docs-site/` and use MkDocs Material. |
| 58 | + |
| 59 | +```bash |
| 60 | +cd docs-site |
| 61 | + |
| 62 | +# Create virtual environment (first time only) |
| 63 | +python3 -m venv venv |
| 64 | + |
| 65 | +# Activate virtual environment |
| 66 | +source venv/bin/activate # On Windows: venv\Scripts\activate |
| 67 | + |
| 68 | +# Install dependencies |
| 69 | +pip install -r requirements.txt |
| 70 | + |
| 71 | +# Live preview at http://127.0.0.1:8000 |
| 72 | +mkdocs serve |
| 73 | + |
| 74 | +# Or build static site into site/ directory |
| 75 | +mkdocs build |
| 76 | +``` |
| 77 | + |
| 78 | +## 7. Publishing |
| 79 | + |
| 80 | +### Library |
| 81 | + |
| 82 | +1. Ensure `npm run build` output is up to date |
| 83 | +2. Update version in `package.json` if needed |
| 84 | +3. From the repo root: |
| 85 | + ```bash |
| 86 | + npm publish --access public |
| 87 | + ``` |
0 commit comments