You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit f518879
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: README.md
+84-40Lines changed: 84 additions & 40 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -111,60 +111,104 @@ cd RapiDoc
111
111
npm install
112
112
```
113
113
114
-
### 2. Development Server
115
-
Start the local documentation and examples server:
114
+
### 2. Development Server & Live Debugging
115
+
Start the local documentation and interactive examples showcase:
116
116
```bash
117
-
# Start dev server
117
+
# Start dev server (http://localhost:4321)
118
118
npm run dev
119
119
120
120
# Stop background dev server
121
121
npm run stop
122
122
```
123
123
- Open `http://localhost:4321` in your browser.
124
-
-**Instant HMR:** During development, the server maps directly to `packages/rapidoc/src/index.js`. Any edit you make to RapiDoc's component source reloads immediately in your browser without requiring a rebuild!
124
+
-**Live Unminified ES Modules:** In development mode (`npm run dev`), the Astro dev server bypasses pre-compiled production bundles and serves live ES modules directly from `packages/rapidoc/src/index.js`.
125
+
-**Full DevTools & Console Visibility:** All `console.log`, `console.warn`, `console.error`, and `debugger` breakpoints remain completely intact with original file names and exact line numbers (e.g., `rapidoc.js:516`).
126
+
-**Instant Browser Reloading:** Component changes in `packages/rapidoc/src/` trigger immediate hot reloads without waiting for a full Rollup/Vite compilation cycle.
125
127
126
-
### 3. Building
128
+
---
127
129
128
-
| Command | Description |
129
-
|---|---|
130
-
|`npm run dev`| Starts the Astro development server. |
131
-
|`npm run stop`| Stops the running Astro development server. |
132
-
|`npm run build`| Builds both the `rapidoc` web component library and the `docs` site. |
133
-
|`npm run build:rapidoc`| Builds only the RapiDoc web component (`packages/rapidoc/dist/rapidoc-min.js`). |
134
-
|`npm run build:docs`| Builds only the Astro documentation site (`docs/generated-docs/`). |
135
-
|`npm run build:size`| Builds RapiDoc with a visual bundle analyzer report (`dist/stats.html`). |
136
-
|`npm run preview`| Previews the built production documentation site locally. |
130
+
### 3. Build Process & Workspace Integration
137
131
138
-
### 4. Code Quality & Linting
132
+
This monorepo contains multiple packages: the core Web Component library (**`packages/rapidoc`**) and the documentation showcase site (**`docs`**). The build system coordinates them as follows:
139
133
140
-
```bash
141
-
# Run ESLint on packages/rapidoc
142
-
npm run lint
134
+
#### Core Library Production Build (`npm run build:rapidoc`)
- Compiles the RapiDoc custom element in library mode using [Vite 6](https://vitejs.dev/).
138
+
- Inlines and bundles runtime dependencies (`lit`, `@scalar/openapi-parser`, `marked`, `microlighter`, `github-slugger`) into a standalone bundle with **zero runtime external dependencies**.
139
+
- Minifies Lit templates using `@lit-labs/rollup-plugin-minify-html-literals`.
140
+
- Strips `console.*` and `debugger` calls via a custom esbuild transform for optimal performance and clean production distribution.
141
+
- Injects the license and version header banner.
143
142
144
-
# Run Lit Analyzer for Web Component template validation
145
-
npm run analyze
143
+
#### Core Library Development Build (`npm run build:rapidoc:dev`)
- Compiles the standalone library bundle with `mode: 'development'`.
147
+
- Disables template and esbuild minification, preserves all `console` and `debugger` statements, and emits full external source maps.
148
+
- Useful when you need to test the bundled `<rapi-doc>` script tag artifact in external standalone HTML pages or apps with full DevTools logging.
146
149
147
-
# Check code formatting with Prettier
148
-
npm run format
150
+
#### Full Monorepo Build (`npm run build`)
151
+
-**Scope:** Root monorepo
152
+
- Sequentially executes `npm run build:rapidoc` followed by `npm run build:docs`.
149
153
150
-
# Automatically fix code formatting
151
-
npm run format-fix
152
-
```
154
+
---
153
155
154
-
### 5. Publishing to npm
156
+
### 4. How Astro Docs Consumes RapiDoc (`rapidoc-min.js`)
155
157
156
-
To publish a new version of the core `rapidoc` package to npm:
158
+
Astro documentation and example pages include the component via `<script type="module" src="/rapidoc/rapidoc-min.js"></script>`. How this URL is resolved depends on whether you are developing locally or generating a production build:
159
+
160
+
1.**During Local Development (`npm run dev`):**
161
+
- The Astro dev server middleware (in `docs/astro.config.mjs`) **intercepts** all requests for `/rapidoc/rapidoc-min.js` (and `/rapidoc/rapidoc.js`).
162
+
- Instead of reading any pre-built static file, it directly imports and serves `packages/rapidoc/src/index.js` live through Vite's module pipeline.
163
+
- You get instant HMR, unminified source code, active `console.*` logging, and sourcemaps with exact line numbers in browser DevTools. Neither `dist/` nor `generated-docs/` is served during development.
164
+
165
+
2.**During Production Site Build (`npm run build:docs` / `npm run build`):**
166
+
- The custom `build-rapidoc` Vite plugin in `docs/astro.config.mjs` runs during build initialization:
167
+
1. It verifies that `packages/rapidoc/dist/rapidoc-min.js` is compiled (triggering a Vite library build if missing).
168
+
2. It copies `packages/rapidoc/dist/rapidoc-min.js` into **`docs/dist/rapidoc/rapidoc-min.js`**, so that the static site deployed to GitHub Pages serves the production bundle.
169
+
3. If the local **`docs/generated-docs/`** directory exists, it also synchronizes `rapidoc-min.js` into **`docs/generated-docs/rapidoc/rapidoc-min.js`** to keep the static snapshot folder up to date with the newly built component.
170
+
171
+
---
157
172
158
-
1.**Bump Version:** Update `"version"` in `packages/rapidoc/package.json` (e.g. `9.3.9`).
159
-
2.**Build Library Bundle:**
160
-
```bash
161
-
npm run build:rapidoc
162
-
```
163
-
3.**Publish to npm Registry:**
164
-
```bash
165
-
npm run publish:rapidoc
166
-
```
167
-
*(Or navigate into `cd packages/rapidoc && npm publish`)*.
173
+
### 5. NPM Command Reference
174
+
175
+
All primary commands can be run from the root of the repository:
176
+
177
+
#### Development & Live Preview
178
+
| Command | Workspace | Description |
179
+
|---|---|---|
180
+
|`npm run dev`|`docs`| Launches Astro documentation & showcase dev server (`http://localhost:4321`) with live unminified RapiDoc ESM directly from source. |
181
+
|`npm run stop`|`docs`| Terminates background Astro dev server processes. |
182
+
|`npm run preview`|`docs`| Previews the production build of the documentation site (`docs/dist`) locally. |
183
+
184
+
#### Building
185
+
| Command | Workspace | Description |
186
+
|---|---|---|
187
+
|`npm run build`| Monorepo | Sequentially builds production RapiDoc library bundle and the Astro documentation site. |
188
+
|`npm run build:rapidoc`|`rapidoc`| Compiles production, minified Web Component bundle to `packages/rapidoc/dist/rapidoc-min.js`. |
189
+
|`npm run build:rapidoc:dev`|`rapidoc`| Compiles unminified Web Component bundle with source maps & console logs to `packages/rapidoc/dist/`. |
190
+
|`npm run build:docs`|`docs`| Builds the production Astro documentation site into `docs/dist/` (and syncs bundle to `generated-docs/`). |
191
+
|`npm run build:size`|`rapidoc`| Builds RapiDoc with `ANALYZE=true` and opens an interactive bundle visualizer (`dist/stats.html`). |
192
+
193
+
#### Testing & Benchmarks
194
+
| Command | Workspace | Description |
195
+
|---|---|---|
196
+
|`npm run test:unit`| Monorepo | Runs Node.js native unit tests (`tests/unit/*.test.js`) for schema parsers and AST converters. |
197
+
|`npm run test:perf`| Monorepo | Runs spec parsing, circular ref, and dereferencing benchmarks (`tests/perf/benchmark.js`). |
198
+
|`npm run test:render`| Monorepo | Measures headless browser rendering performance across render styles using Puppeteer (`tests/perf/render-benchmark.js`). |
199
+
200
+
#### Code Quality & Formatting
201
+
| Command | Workspace | Description |
202
+
|---|---|---|
203
+
|`npm run lint`|`rapidoc`| Runs ESLint on `packages/rapidoc/src/**/*.js` with Lit rules. |
204
+
|`npm run analyze`|`rapidoc`| Runs Lit Analyzer to validate custom element templates and bindings. |
205
+
|`npm run format`| Monorepo | Checks code formatting against `.prettierrc` across packages and docs. |
206
+
|`npm run format-fix`| Monorepo | Automatically formats code using Prettier across packages and docs. |
207
+
208
+
#### Publishing
209
+
| Command | Workspace | Description |
210
+
|---|---|---|
211
+
|`npm run publish:rapidoc`|`rapidoc`| Publishes the `rapidoc` package to the npm registry. |
168
212
169
213
---
170
214
@@ -174,9 +218,9 @@ The documentation site is built with modern **Astro** using clean, extensionless
174
218
175
219
### Deployment via GitHub Actions
176
220
When code is pushed to `master` or `main`, the [deploy-docs.yml](file:///Users/mrin/work/astro-rapidoc/.github/workflows/deploy-docs.yml) GitHub Action automatically:
177
-
1. Compiles the `rapidoc` library bundle.
178
-
2. Builds the documentation site (`npm run build:docs`).
179
-
3. Deploys the static output (`docs/generated-docs/`) directly to **GitHub Pages**.
221
+
1. Compiles the `rapidoc` library bundle (`packages/rapidoc/dist/rapidoc-min.js`).
222
+
2. Builds the Astro documentation site into `docs/dist/`(`npm run build`).
223
+
3. Deploys the static output directory (`docs/dist/`) directly to **GitHub Pages** using `@actions/deploy-pages`.
180
224
181
225
> **Note on GitHub Pages Configuration:**
182
226
> In repository settings under **Settings → Pages**, set **Source** to **GitHub Actions**. This keeps the repository clean by eliminating the need to commit compiled static HTML files into git branches.
Copy file name to clipboardExpand all lines: packages/rapidoc/README.md
+84-40Lines changed: 84 additions & 40 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -111,60 +111,104 @@ cd RapiDoc
111
111
npm install
112
112
```
113
113
114
-
### 2. Development Server
115
-
Start the local documentation and examples server:
114
+
### 2. Development Server & Live Debugging
115
+
Start the local documentation and interactive examples showcase:
116
116
```bash
117
-
# Start dev server
117
+
# Start dev server (http://localhost:4321)
118
118
npm run dev
119
119
120
120
# Stop background dev server
121
121
npm run stop
122
122
```
123
123
- Open `http://localhost:4321` in your browser.
124
-
-**Instant HMR:** During development, the server maps directly to `packages/rapidoc/src/index.js`. Any edit you make to RapiDoc's component source reloads immediately in your browser without requiring a rebuild!
124
+
-**Live Unminified ES Modules:** In development mode (`npm run dev`), the Astro dev server bypasses pre-compiled production bundles and serves live ES modules directly from `packages/rapidoc/src/index.js`.
125
+
-**Full DevTools & Console Visibility:** All `console.log`, `console.warn`, `console.error`, and `debugger` breakpoints remain completely intact with original file names and exact line numbers (e.g., `rapidoc.js:516`).
126
+
-**Instant Browser Reloading:** Component changes in `packages/rapidoc/src/` trigger immediate hot reloads without waiting for a full Rollup/Vite compilation cycle.
125
127
126
-
### 3. Building
128
+
---
127
129
128
-
| Command | Description |
129
-
|---|---|
130
-
|`npm run dev`| Starts the Astro development server. |
131
-
|`npm run stop`| Stops the running Astro development server. |
132
-
|`npm run build`| Builds both the `rapidoc` web component library and the `docs` site. |
133
-
|`npm run build:rapidoc`| Builds only the RapiDoc web component (`packages/rapidoc/dist/rapidoc-min.js`). |
134
-
|`npm run build:docs`| Builds only the Astro documentation site (`docs/generated-docs/`). |
135
-
|`npm run build:size`| Builds RapiDoc with a visual bundle analyzer report (`dist/stats.html`). |
136
-
|`npm run preview`| Previews the built production documentation site locally. |
130
+
### 3. Build Process & Workspace Integration
137
131
138
-
### 4. Code Quality & Linting
132
+
This monorepo contains multiple packages: the core Web Component library (**`packages/rapidoc`**) and the documentation showcase site (**`docs`**). The build system coordinates them as follows:
139
133
140
-
```bash
141
-
# Run ESLint on packages/rapidoc
142
-
npm run lint
134
+
#### Core Library Production Build (`npm run build:rapidoc`)
- Compiles the RapiDoc custom element in library mode using [Vite 6](https://vitejs.dev/).
138
+
- Inlines and bundles runtime dependencies (`lit`, `@scalar/openapi-parser`, `marked`, `microlighter`, `github-slugger`) into a standalone bundle with **zero runtime external dependencies**.
139
+
- Minifies Lit templates using `@lit-labs/rollup-plugin-minify-html-literals`.
140
+
- Strips `console.*` and `debugger` calls via a custom esbuild transform for optimal performance and clean production distribution.
141
+
- Injects the license and version header banner.
143
142
144
-
# Run Lit Analyzer for Web Component template validation
145
-
npm run analyze
143
+
#### Core Library Development Build (`npm run build:rapidoc:dev`)
- Compiles the standalone library bundle with `mode: 'development'`.
147
+
- Disables template and esbuild minification, preserves all `console` and `debugger` statements, and emits full external source maps.
148
+
- Useful when you need to test the bundled `<rapi-doc>` script tag artifact in external standalone HTML pages or apps with full DevTools logging.
146
149
147
-
# Check code formatting with Prettier
148
-
npm run format
150
+
#### Full Monorepo Build (`npm run build`)
151
+
-**Scope:** Root monorepo
152
+
- Sequentially executes `npm run build:rapidoc` followed by `npm run build:docs`.
149
153
150
-
# Automatically fix code formatting
151
-
npm run format-fix
152
-
```
154
+
---
153
155
154
-
### 5. Publishing to npm
156
+
### 4. How Astro Docs Consumes RapiDoc (`rapidoc-min.js`)
155
157
156
-
To publish a new version of the core `rapidoc` package to npm:
158
+
Astro documentation and example pages include the component via `<script type="module" src="/rapidoc/rapidoc-min.js"></script>`. How this URL is resolved depends on whether you are developing locally or generating a production build:
159
+
160
+
1.**During Local Development (`npm run dev`):**
161
+
- The Astro dev server middleware (in `docs/astro.config.mjs`) **intercepts** all requests for `/rapidoc/rapidoc-min.js` (and `/rapidoc/rapidoc.js`).
162
+
- Instead of reading any pre-built static file, it directly imports and serves `packages/rapidoc/src/index.js` live through Vite's module pipeline.
163
+
- You get instant HMR, unminified source code, active `console.*` logging, and sourcemaps with exact line numbers in browser DevTools. Neither `dist/` nor `generated-docs/` is served during development.
164
+
165
+
2.**During Production Site Build (`npm run build:docs` / `npm run build`):**
166
+
- The custom `build-rapidoc` Vite plugin in `docs/astro.config.mjs` runs during build initialization:
167
+
1. It verifies that `packages/rapidoc/dist/rapidoc-min.js` is compiled (triggering a Vite library build if missing).
168
+
2. It copies `packages/rapidoc/dist/rapidoc-min.js` into **`docs/dist/rapidoc/rapidoc-min.js`**, so that the static site deployed to GitHub Pages serves the production bundle.
169
+
3. If the local **`docs/generated-docs/`** directory exists, it also synchronizes `rapidoc-min.js` into **`docs/generated-docs/rapidoc/rapidoc-min.js`** to keep the static snapshot folder up to date with the newly built component.
170
+
171
+
---
157
172
158
-
1.**Bump Version:** Update `"version"` in `packages/rapidoc/package.json` (e.g. `9.3.9`).
159
-
2.**Build Library Bundle:**
160
-
```bash
161
-
npm run build:rapidoc
162
-
```
163
-
3.**Publish to npm Registry:**
164
-
```bash
165
-
npm run publish:rapidoc
166
-
```
167
-
*(Or navigate into `cd packages/rapidoc && npm publish`)*.
173
+
### 5. NPM Command Reference
174
+
175
+
All primary commands can be run from the root of the repository:
176
+
177
+
#### Development & Live Preview
178
+
| Command | Workspace | Description |
179
+
|---|---|---|
180
+
|`npm run dev`|`docs`| Launches Astro documentation & showcase dev server (`http://localhost:4321`) with live unminified RapiDoc ESM directly from source. |
181
+
|`npm run stop`|`docs`| Terminates background Astro dev server processes. |
182
+
|`npm run preview`|`docs`| Previews the production build of the documentation site (`docs/dist`) locally. |
183
+
184
+
#### Building
185
+
| Command | Workspace | Description |
186
+
|---|---|---|
187
+
|`npm run build`| Monorepo | Sequentially builds production RapiDoc library bundle and the Astro documentation site. |
188
+
|`npm run build:rapidoc`|`rapidoc`| Compiles production, minified Web Component bundle to `packages/rapidoc/dist/rapidoc-min.js`. |
189
+
|`npm run build:rapidoc:dev`|`rapidoc`| Compiles unminified Web Component bundle with source maps & console logs to `packages/rapidoc/dist/`. |
190
+
|`npm run build:docs`|`docs`| Builds the production Astro documentation site into `docs/dist/` (and syncs bundle to `generated-docs/`). |
191
+
|`npm run build:size`|`rapidoc`| Builds RapiDoc with `ANALYZE=true` and opens an interactive bundle visualizer (`dist/stats.html`). |
192
+
193
+
#### Testing & Benchmarks
194
+
| Command | Workspace | Description |
195
+
|---|---|---|
196
+
|`npm run test:unit`| Monorepo | Runs Node.js native unit tests (`tests/unit/*.test.js`) for schema parsers and AST converters. |
197
+
|`npm run test:perf`| Monorepo | Runs spec parsing, circular ref, and dereferencing benchmarks (`tests/perf/benchmark.js`). |
198
+
|`npm run test:render`| Monorepo | Measures headless browser rendering performance across render styles using Puppeteer (`tests/perf/render-benchmark.js`). |
199
+
200
+
#### Code Quality & Formatting
201
+
| Command | Workspace | Description |
202
+
|---|---|---|
203
+
|`npm run lint`|`rapidoc`| Runs ESLint on `packages/rapidoc/src/**/*.js` with Lit rules. |
204
+
|`npm run analyze`|`rapidoc`| Runs Lit Analyzer to validate custom element templates and bindings. |
205
+
|`npm run format`| Monorepo | Checks code formatting against `.prettierrc` across packages and docs. |
206
+
|`npm run format-fix`| Monorepo | Automatically formats code using Prettier across packages and docs. |
207
+
208
+
#### Publishing
209
+
| Command | Workspace | Description |
210
+
|---|---|---|
211
+
|`npm run publish:rapidoc`|`rapidoc`| Publishes the `rapidoc` package to the npm registry. |
168
212
169
213
---
170
214
@@ -174,9 +218,9 @@ The documentation site is built with modern **Astro** using clean, extensionless
174
218
175
219
### Deployment via GitHub Actions
176
220
When code is pushed to `master` or `main`, the [deploy-docs.yml](file:///Users/mrin/work/astro-rapidoc/.github/workflows/deploy-docs.yml) GitHub Action automatically:
177
-
1. Compiles the `rapidoc` library bundle.
178
-
2. Builds the documentation site (`npm run build:docs`).
179
-
3. Deploys the static output (`docs/generated-docs/`) directly to **GitHub Pages**.
221
+
1. Compiles the `rapidoc` library bundle (`packages/rapidoc/dist/rapidoc-min.js`).
222
+
2. Builds the Astro documentation site into `docs/dist/`(`npm run build`).
223
+
3. Deploys the static output directory (`docs/dist/`) directly to **GitHub Pages** using `@actions/deploy-pages`.
180
224
181
225
> **Note on GitHub Pages Configuration:**
182
226
> In repository settings under **Settings → Pages**, set **Source** to **GitHub Actions**. This keeps the repository clean by eliminating the need to commit compiled static HTML files into git branches.
0 commit comments