@shadow-js/vite 0.2.0 → 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +12 -0
- package/LICENSE +2 -2
- package/README.md +123 -236
- package/dist/dev/index.d.ts +100 -0
- package/dist/dev/index.js +144 -0
- package/dist/dev/index.js.map +1 -0
- package/dist/dev/mdx.d.ts +97 -0
- package/dist/dev/mdx.js +214 -0
- package/dist/dev/mdx.js.map +1 -0
- package/dist/mdx-env.d.ts +26 -0
- package/dist/prod/index.js +2 -0
- package/dist/prod/index.js.map +1 -0
- package/dist/prod/mdx.js +2 -0
- package/dist/prod/mdx.js.map +1 -0
- package/package.json +68 -45
- package/dist/index.cjs +0 -59
- package/dist/index.cjs.map +0 -1
- package/dist/index.d.cts +0 -63
- package/dist/index.d.ts +0 -63
- package/dist/index.js +0 -57
- package/dist/index.js.map +0 -1
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 1.0.0
|
|
4
|
+
|
|
5
|
+
### Added
|
|
6
|
+
|
|
7
|
+
- Vite integration for the ShadowJS compiler, including DOM and server transforms.
|
|
8
|
+
- Development updates and hot module replacement for ShadowJS components.
|
|
9
|
+
- `include` and `exclude` patterns with a `g` or `y` flag match the same on every call: the plugin matches with a copy of the pattern without those flags.
|
|
10
|
+
- `plugins` option: compiler plugins (`CompilerPlugin` from `@shadow-js/compiler`) that run in the build on every compiled module, in the browser and server transforms. The list is validated when `shadow()` is called; plugin errors fail the build with the plugin's name, the file, the line and the column, and plugin warnings go to Vite's warning log.
|
|
11
|
+
- Vite 7.0 and newer are supported next to Vite 8 (peer range `^7.0.0 || ^8.0.0`).
|
|
12
|
+
- `@shadow-js/vite/mdx`: `shadowMdx()` compiles `.mdx` files into components through `@mdx-js/mdx` (optional peer) and the ShadowJS compiler in one step, with remark, rehype and recma plugins, replaceable Markdown elements (`components` prop, `wrapper`) or static ones (`elements: "static"`), and types for `*.mdx` modules in `@shadow-js/vite/mdx-env`.
|
package/LICENSE
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
MIT License
|
|
2
2
|
|
|
3
|
-
Copyright (c)
|
|
3
|
+
Copyright (c) 2026 ShadowJS contributors
|
|
4
4
|
|
|
5
5
|
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
6
|
of this software and associated documentation files (the "Software"), to deal
|
|
@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
|
18
18
|
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
19
|
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
20
|
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
-
SOFTWARE.
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,298 +1,185 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @shadow-js/vite
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
3
|
+
The Vite plugin for ShadowJS. It runs [`@shadow-js/compiler`](../compiler/README.md) on every
|
|
4
|
+
`.jsx` and `.tsx` file before Vite's own JSX handling, so the code Vite sees contains no JSX. In an
|
|
5
|
+
SSR build it emits the server target. It also points Vite's dependency scanning at the ShadowJS JSX
|
|
6
|
+
runtime types, de-duplicates `@shadow-js/core` and `@shadow-js/web`, and configures Vitest for
|
|
7
|
+
DOM tests. Vite is the only supported host in 1.0.0; this is a plain Vite plugin, not an unplugin.
|
|
6
8
|
|
|
7
|
-
|
|
9
|
+
## Install
|
|
8
10
|
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
- **⚡ Hot Module Replacement**: Instant updates during development
|
|
12
|
-
- **🎯 JSX Compilation**: Automatic ShadowJS JSX transformations
|
|
13
|
-
- **🔧 Zero Configuration**: Works out of the box with sensible defaults
|
|
14
|
-
- **🎨 TypeScript Support**: Full TypeScript and TSX compilation
|
|
15
|
-
- **📦 Optimized Builds**: Production-ready bundle optimization
|
|
16
|
-
- **🔍 Source Maps**: Accurate debugging with source map support
|
|
17
|
-
- **🎭 Development Server**: Fast development server with HMR
|
|
18
|
-
- **📱 Modern Standards**: ES2022+ with modern browser support
|
|
19
|
-
|
|
20
|
-
## 📦 Installation
|
|
21
|
-
|
|
22
|
-
```bash
|
|
23
|
-
npm install @shadow-js/vite
|
|
11
|
+
```sh
|
|
12
|
+
npm install -D @shadow-js/vite vite
|
|
24
13
|
```
|
|
25
14
|
|
|
26
|
-
|
|
15
|
+
Requires Vite 7 or 8 (`vite` is an optional peer dependency, `^7.0.0 || ^8.0.0`). `@shadow-js/compiler` is installed
|
|
16
|
+
as a dependency. ShadowJS 1.0.0 is not on npm yet; until it is published, install it from a local
|
|
17
|
+
checkout of this repository.
|
|
27
18
|
|
|
28
|
-
|
|
29
|
-
npm install @shadow-js/core @shadow-js/vite
|
|
30
|
-
```
|
|
19
|
+
## Example
|
|
31
20
|
|
|
32
|
-
|
|
21
|
+
Add the plugin to `vite.config.ts`. The named export `shadow` and the default export are the same
|
|
22
|
+
function.
|
|
33
23
|
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
**vite.config.ts**
|
|
37
|
-
|
|
38
|
-
```typescript
|
|
39
|
-
import { defineConfig } from "vite";
|
|
24
|
+
```ts title="vite.config.ts" typecheck
|
|
40
25
|
import shadow from "@shadow-js/vite";
|
|
26
|
+
import { defineConfig } from "vite";
|
|
41
27
|
|
|
42
28
|
export default defineConfig({
|
|
43
29
|
plugins: [shadow()],
|
|
44
30
|
});
|
|
45
31
|
```
|
|
46
32
|
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
function App() {
|
|
53
|
-
const [count, setCount] = useStore(0);
|
|
54
|
-
|
|
55
|
-
return (
|
|
56
|
-
<div>
|
|
57
|
-
<h1>ShadowJS Counter</h1>
|
|
58
|
-
<button onClick={() => setCount((c) => c + 1)}>Count: {count()}</button>
|
|
59
|
-
<Show when={count() > 5}>
|
|
60
|
-
<p>🎉 You reached {count()}!</p>
|
|
61
|
-
</Show>
|
|
62
|
-
</div>
|
|
63
|
-
);
|
|
64
|
-
}
|
|
65
|
-
|
|
66
|
-
export default App;
|
|
67
|
-
```
|
|
68
|
-
|
|
69
|
-
**src/main.ts**
|
|
70
|
-
|
|
71
|
-
```typescript
|
|
72
|
-
import { render } from "@shadow-js/core";
|
|
73
|
-
import App from "./App";
|
|
74
|
-
|
|
75
|
-
render(App, document.getElementById("app")!);
|
|
76
|
-
```
|
|
77
|
-
|
|
78
|
-
**index.html**
|
|
79
|
-
|
|
80
|
-
```html
|
|
81
|
-
<!DOCTYPE html>
|
|
82
|
-
<html lang="en">
|
|
83
|
-
<head>
|
|
84
|
-
<meta charset="UTF-8" />
|
|
85
|
-
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
|
86
|
-
<title>ShadowJS App</title>
|
|
87
|
-
</head>
|
|
88
|
-
<body>
|
|
89
|
-
<div id="app"></div>
|
|
90
|
-
<script type="module" src="/src/main.ts"></script>
|
|
91
|
-
</body>
|
|
92
|
-
</html>
|
|
93
|
-
```
|
|
94
|
-
|
|
95
|
-
### Development Commands
|
|
96
|
-
|
|
97
|
-
```bash
|
|
98
|
-
# Start development server
|
|
99
|
-
npm run dev
|
|
100
|
-
|
|
101
|
-
# Build for production
|
|
102
|
-
npm run build
|
|
103
|
-
|
|
104
|
-
# Preview production build
|
|
105
|
-
npm run preview
|
|
106
|
-
```
|
|
107
|
-
|
|
108
|
-
## 🎯 How It Works
|
|
109
|
-
|
|
110
|
-
The plugin integrates ShadowJS with Vite's build pipeline:
|
|
33
|
+
The plugin is an ordinary Vite plugin object, so its behavior can be checked without starting a
|
|
34
|
+
server: call its `config` and `transform` hooks the way Vite does. In a production build a `.tsx`
|
|
35
|
+
file comes back compiled, files the plugin does not handle come back as `null`, and an SSR
|
|
36
|
+
transform imports from `@shadow-js/web/server`.
|
|
111
37
|
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
- **Hot Module Replacement**: Instant updates without page refresh
|
|
115
|
-
- **Source Maps**: Accurate debugging information
|
|
116
|
-
- **Error Overlay**: Clear error messages in browser
|
|
38
|
+
```ts title="plugin.ts" run output="shadowjs pre\ncompiled: true\nplain ts: null\nssr: true"
|
|
39
|
+
import shadow from "@shadow-js/vite";
|
|
117
40
|
|
|
118
|
-
|
|
41
|
+
type Config = (config: object, env: { command: string; mode: string }) => unknown;
|
|
42
|
+
type Transform = (
|
|
43
|
+
this: { error(message: string): never },
|
|
44
|
+
code: string,
|
|
45
|
+
id: string,
|
|
46
|
+
options?: { ssr?: boolean },
|
|
47
|
+
) => { code: string } | null;
|
|
48
|
+
|
|
49
|
+
const plugin = shadow();
|
|
50
|
+
const config = plugin.config as Config;
|
|
51
|
+
const transform = plugin.transform as Transform;
|
|
52
|
+
const context = {
|
|
53
|
+
error(message: string): never {
|
|
54
|
+
throw new Error(message);
|
|
55
|
+
},
|
|
56
|
+
};
|
|
119
57
|
|
|
120
|
-
|
|
121
|
-
- **TypeScript Compilation**: Converts TypeScript to JavaScript
|
|
122
|
-
- **JSX Runtime Injection**: Automatically imports ShadowJS runtime
|
|
123
|
-
- **Code Splitting**: Optimizes bundle size with code splitting
|
|
124
|
-
- **Minification**: Production-ready code minification
|
|
58
|
+
config({}, { command: "build", mode: "production" });
|
|
125
59
|
|
|
126
|
-
|
|
60
|
+
const source = "export const App = () => <button>hi</button>;";
|
|
61
|
+
const compiled = transform.call(context, source, "/app/app.tsx");
|
|
62
|
+
const server = transform.call(context, source, "/app/app.tsx", { ssr: true });
|
|
127
63
|
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
↓
|
|
133
|
-
SWC (TypeScript → JavaScript)
|
|
134
|
-
↓
|
|
135
|
-
Vite (Bundling & Optimization)
|
|
136
|
-
↓
|
|
137
|
-
Output Bundle
|
|
64
|
+
console.log(plugin.name, plugin.enforce);
|
|
65
|
+
console.log(`compiled: ${compiled?.code.includes("template(") === true}`);
|
|
66
|
+
console.log(`plain ts: ${transform.call(context, "export const n = 1;", "/app/n.ts")}`);
|
|
67
|
+
console.log(`ssr: ${server?.code.includes("@shadow-js/web/server") === true}`);
|
|
138
68
|
```
|
|
139
69
|
|
|
140
|
-
|
|
70
|
+
### Testing with Vitest
|
|
141
71
|
|
|
142
|
-
|
|
72
|
+
Tests need the compiler too. Use the same plugin in `vitest.config.ts`. When the test environment
|
|
73
|
+
is `happy-dom` or `jsdom` the plugin selects the browser build of ShadowJS and inlines it; with a
|
|
74
|
+
`node` environment it keeps the server build. Set `domTests` explicitly if you pick the environment
|
|
75
|
+
per file; tests that call `renderToString` want `domTests: false`.
|
|
143
76
|
|
|
144
|
-
```
|
|
145
|
-
// vite.config.ts
|
|
146
|
-
import { defineConfig } from "vite";
|
|
77
|
+
```ts title="vitest.config.ts" typecheck
|
|
147
78
|
import shadow from "@shadow-js/vite";
|
|
79
|
+
import { defineConfig } from "vitest/config";
|
|
148
80
|
|
|
149
81
|
export default defineConfig({
|
|
150
82
|
plugins: [shadow()],
|
|
151
|
-
|
|
83
|
+
test: { environment: "happy-dom" },
|
|
152
84
|
});
|
|
153
85
|
```
|
|
154
86
|
|
|
155
|
-
|
|
87
|
+
With Vitest `projects` the environment is set per project, and a plugin in the root `plugins` cannot
|
|
88
|
+
see it. Give the DOM project its own plugin with `domTests: true` (it then also inlines `@shadow-js/*`
|
|
89
|
+
for that project only); a node project keeps the server build:
|
|
156
90
|
|
|
157
|
-
```
|
|
158
|
-
// vite.config.ts
|
|
159
|
-
import { defineConfig } from "vite";
|
|
91
|
+
```ts title="vitest.config.ts" typecheck
|
|
160
92
|
import shadow from "@shadow-js/vite";
|
|
93
|
+
import { defineConfig } from "vitest/config";
|
|
161
94
|
|
|
162
95
|
export default defineConfig({
|
|
163
|
-
plugins: [
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
},
|
|
174
|
-
|
|
175
|
-
build: {
|
|
176
|
-
target: "es2022",
|
|
177
|
-
minify: "esbuild",
|
|
178
|
-
},
|
|
179
|
-
|
|
180
|
-
// TypeScript configuration
|
|
181
|
-
esbuild: {
|
|
182
|
-
// Vite handles TypeScript compilation
|
|
96
|
+
plugins: [shadow()],
|
|
97
|
+
test: {
|
|
98
|
+
projects: [
|
|
99
|
+
{ extends: true, test: { name: "node", environment: "node", include: ["src/**/*.test.ts"] } },
|
|
100
|
+
{
|
|
101
|
+
extends: true,
|
|
102
|
+
plugins: [shadow({ domTests: true })],
|
|
103
|
+
test: { name: "dom", environment: "happy-dom", include: ["src/**/*.dom.test.tsx"] },
|
|
104
|
+
},
|
|
105
|
+
],
|
|
183
106
|
},
|
|
184
107
|
});
|
|
185
108
|
```
|
|
186
109
|
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
The ShadowJS plugin works well with other Vite plugins:
|
|
190
|
-
|
|
191
|
-
```typescript
|
|
192
|
-
import { defineConfig } from "vite";
|
|
193
|
-
import shadow from "@shadow-js/vite";
|
|
194
|
-
import { viteStaticCopy } from "vite-plugin-static-copy";
|
|
195
|
-
|
|
196
|
-
export default defineConfig({
|
|
197
|
-
plugins: [
|
|
198
|
-
shadow(),
|
|
199
|
-
viteStaticCopy({
|
|
200
|
-
targets: [
|
|
201
|
-
{
|
|
202
|
-
src: "static/*",
|
|
203
|
-
dest: "assets",
|
|
204
|
-
},
|
|
205
|
-
],
|
|
206
|
-
}),
|
|
207
|
-
],
|
|
208
|
-
});
|
|
209
|
-
```
|
|
210
|
-
|
|
211
|
-
## 🏗️ Plugin Architecture
|
|
110
|
+
## Options
|
|
212
111
|
|
|
213
|
-
|
|
112
|
+
`shadow(options?)` takes a `ShadowPluginOptions` object.
|
|
214
113
|
|
|
215
|
-
|
|
|
216
|
-
|
|
|
217
|
-
|
|
|
218
|
-
|
|
|
219
|
-
|
|
|
220
|
-
|
|
|
221
|
-
|
|
|
114
|
+
| Option | Default | Description |
|
|
115
|
+
| --- | --- | --- |
|
|
116
|
+
| `include` | `/\.[cm]?[jt]sx$/` | Files to compile. A `g` or `y` flag is ignored. |
|
|
117
|
+
| `exclude` | `node_modules` | Files to skip. |
|
|
118
|
+
| `moduleName` | `@shadow-js/web` | Module the compiled code imports runtime helpers from. |
|
|
119
|
+
| `autoReactive` | `true` | Keep constants computed from reactive reads live without a function (forgiving reactivity). |
|
|
120
|
+
| `hmr` | `true` | Hot-update components in place during `vite dev`. |
|
|
121
|
+
| `dev` | Vite dev mode | Force development output (component names, extra checks). |
|
|
122
|
+
| `domTests` | detected | Run the browser build under Vitest. On by default for `happy-dom` and `jsdom`. |
|
|
123
|
+
| `plugins` | none | [Compiler plugins](https://shadowjs.net/guides/compiler/) (`CompilerPlugin` from `@shadow-js/compiler`) that run in the build on every compiled module. Validated when `shadow()` is called; errors fail the build with the plugin's name and the position, warnings go to Vite's log. |
|
|
222
124
|
|
|
223
|
-
|
|
125
|
+
## Hot updates
|
|
224
126
|
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
127
|
+
The plugin turns on the compiler's `hmr` option in `vite dev` (never in a build, for SSR transforms
|
|
128
|
+
or under a test runner). The compiled module registers its top-level components with
|
|
129
|
+
`@shadow-js/web/hmr`, so an edit re-renders the instances of the edited component while parents and
|
|
130
|
+
siblings keep their state; a module that exports only components accepts its own update. This is
|
|
131
|
+
covered by the unit tests of the compiler and of the plugin (`[HMR-01]` to `[HMR-06]`, `[VIT-04]`).
|
|
132
|
+
The browser test tier also exercises hot updates in a real browser.
|
|
230
133
|
|
|
231
|
-
|
|
134
|
+
## MDX
|
|
232
135
|
|
|
233
|
-
-
|
|
234
|
-
- **Error Boundaries**: Development-friendly error handling
|
|
235
|
-
- **Console Integration**: Clear logging and debugging messages
|
|
236
|
-
- **Type Checking**: Real-time TypeScript error reporting
|
|
136
|
+
`@shadow-js/vite/mdx` compiles `.mdx` files into components. Install `@mdx-js/mdx` (an optional peer) and list `shadowMdx()` next to `shadow()`:
|
|
237
137
|
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
The plugin provides seamless HMR for ShadowJS components:
|
|
243
|
-
|
|
244
|
-
```jsx
|
|
245
|
-
// This component will hot-reload automatically
|
|
246
|
-
function Counter() {
|
|
247
|
-
const [count, setCount] = useStore(0);
|
|
138
|
+
```ts typecheck
|
|
139
|
+
import shadow from "@shadow-js/vite";
|
|
140
|
+
import { shadowMdx } from "@shadow-js/vite/mdx";
|
|
248
141
|
|
|
249
|
-
|
|
250
|
-
}
|
|
142
|
+
export default { plugins: [shadowMdx(), shadow()] };
|
|
251
143
|
```
|
|
252
144
|
|
|
253
|
-
|
|
145
|
+
`shadowMdx(options?)` takes `include` (default `.mdx`), `exclude`, `remarkPlugins`, `rehypePlugins`, `recmaPlugins`, `remarkRehypeOptions`, `providerImportSource`, `elements` (`"overridable"` looks up each Markdown element in the `components` prop; `"static"` renders them from the template), `mdx` (the compiler's module name or your own function), `plugins` and `moduleName`. The [MDX guide](https://shadowjs.net/guides/mdx/) covers components, frontmatter and content collections. For types, add `/// <reference types="@shadow-js/vite/mdx-env" />` to a `.d.ts` file.
|
|
254
146
|
|
|
255
|
-
|
|
147
|
+
## API
|
|
256
148
|
|
|
257
|
-
|
|
258
|
-
// TypeScript types work perfectly
|
|
259
|
-
function UserComponent({ user }: { user: User }) {
|
|
260
|
-
const [isEditing, setIsEditing] = useStore(false);
|
|
149
|
+
Entry `@shadow-js/vite`. The exports are:
|
|
261
150
|
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
);
|
|
270
|
-
}
|
|
271
|
-
```
|
|
151
|
+
| Export | Description |
|
|
152
|
+
| --- | --- |
|
|
153
|
+
| `shadow` | Returns the Vite plugin: name `shadowjs`, `enforce: "pre"`, with `config` and `transform` hooks. |
|
|
154
|
+
| `default` | The same function as `shadow`. |
|
|
155
|
+
| `ShadowPluginOptions` | The options type. |
|
|
156
|
+
|
|
157
|
+
Entry `@shadow-js/vite/mdx`:
|
|
272
158
|
|
|
273
|
-
|
|
159
|
+
| Export | Description |
|
|
160
|
+
| --- | --- |
|
|
161
|
+
| `shadowMdx` | Returns the MDX plugin: name `shadowjs-mdx`, `enforce: "pre"`. |
|
|
162
|
+
| `ShadowMdxOptions`, `MdxCompile` | The options type and the shape of the `mdx` function. |
|
|
274
163
|
|
|
275
|
-
|
|
164
|
+
`@shadow-js/vite/mdx-env` holds types only (`*.mdx` and `*.md` modules).
|
|
276
165
|
|
|
277
|
-
|
|
166
|
+
## Links
|
|
278
167
|
|
|
279
|
-
-
|
|
280
|
-
-
|
|
281
|
-
- Better error messages
|
|
282
|
-
- Enhanced TypeScript support
|
|
283
|
-
- Additional build optimizations
|
|
168
|
+
- [`@shadow-js/compiler`](../compiler/README.md), [`@shadow-js/web`](../web/README.md), [`@shadow-js/testing`](https://testing.shadowjs.net)
|
|
169
|
+
- [Vite plugin guide](https://shadowjs.net/guides/vite/), [MDX guide](https://shadowjs.net/guides/mdx/)
|
|
284
170
|
|
|
285
|
-
##
|
|
171
|
+
## Dependencies
|
|
286
172
|
|
|
287
|
-
|
|
173
|
+
- Runtime `@shadow-js/compiler` `1.0.0`: compiles component sources in the Vite plugin (`src/index.ts`).
|
|
174
|
+
- Optional peers: `vite` `^7.0.0 || ^8.0.0`: the host for the plugin and the `Plugin` type (`src/index.ts`, `src/mdx.ts`); `@mdx-js/mdx` `^3.0.0`: compiles MDX (`src/mdx.ts`).
|
|
288
175
|
|
|
289
|
-
##
|
|
176
|
+
## Types
|
|
290
177
|
|
|
291
|
-
-
|
|
292
|
-
- **Examples**: [Integration Examples](../../documentation/examples.md)
|
|
293
|
-
- **Issues**: [GitHub Issues](https://github.com/shadowjs-dev/shadow/issues)
|
|
294
|
-
- **Discussions**: [GitHub Discussions](https://github.com/shadowjs-dev/shadow/discussions)
|
|
178
|
+
- Names from the root: `ShadowPluginOptions`. Names from `@shadow-js/vite/mdx`: `ShadowMdxOptions`, `MdxCompile`.
|
|
295
179
|
|
|
296
|
-
|
|
180
|
+
## Support
|
|
297
181
|
|
|
298
|
-
|
|
182
|
+
- Node.js `>=22.12.0`. ESM only: use `import`; `require` is not supported.
|
|
183
|
+
- Browsers: not applicable; the package has no browser target.
|
|
184
|
+
- Versioning: every `@shadow-js/*` package releases together at one version. Upgrade them as one set.
|
|
185
|
+
- Documentation: [ShadowJS documentation](https://shadowjs.net).
|
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
import { CompilerPlugin } from "@shadow-js/compiler";
|
|
2
|
+
import { Plugin } from "vite";
|
|
3
|
+
//#region src/index.d.ts
|
|
4
|
+
/**
|
|
5
|
+
* Options of {@link shadow}. Every member is optional: the defaults compile a ShadowJS app for the
|
|
6
|
+
* browser in `vite dev` and `vite build`, and for the server in SSR builds.
|
|
7
|
+
* @see shadow
|
|
8
|
+
* @since 1.0.0
|
|
9
|
+
*/
|
|
10
|
+
export interface ShadowPluginOptions {
|
|
11
|
+
/**
|
|
12
|
+
* Files to compile, matched against the module id without its query string. Plain `.ts` and `.js`
|
|
13
|
+
* modules are compiled as well when they call `useStore`, whatever this is set to, so a
|
|
14
|
+
* single-value `useStore` there takes the cell path. Files that `exclude` matches are never compiled.
|
|
15
|
+
* @default /\.[cm]?[jt]sx$/ (every `.jsx` and `.tsx` file)
|
|
16
|
+
* A `g` or `y` flag on the pattern is ignored: the pattern is matched from the start of every id.
|
|
17
|
+
*/
|
|
18
|
+
include?: RegExp;
|
|
19
|
+
/**
|
|
20
|
+
* Files to skip. It is checked before `include`, so an excluded file is never compiled.
|
|
21
|
+
* @default /[\\/]node_modules[\\/]/ (any path with a `node_modules` segment)
|
|
22
|
+
*/
|
|
23
|
+
exclude?: RegExp;
|
|
24
|
+
/**
|
|
25
|
+
* Module the compiled code imports its runtime helpers from. The HMR runtime is read from
|
|
26
|
+
* `<moduleName>/hmr`.
|
|
27
|
+
* @default "@shadow-js/web" (`"@shadow-js/web/server"` for SSR transforms)
|
|
28
|
+
*/
|
|
29
|
+
moduleName?: string;
|
|
30
|
+
/**
|
|
31
|
+
* Turn a `const` computed from reactive reads (`const double = count() * 2`) into a live value
|
|
32
|
+
* inside components, so it updates without a function or `useMemo`. Set `false` to keep such
|
|
33
|
+
* constants as written.
|
|
34
|
+
* @default true
|
|
35
|
+
*/
|
|
36
|
+
autoReactive?: boolean;
|
|
37
|
+
/**
|
|
38
|
+
* Hot-update top-level components in place during `vite dev`. It applies to the browser build
|
|
39
|
+
* only: SSR transforms never get it. Test runners never hot-update modules unless this is set.
|
|
40
|
+
* @default true in `vite dev`, false under a test runner
|
|
41
|
+
*/
|
|
42
|
+
hmr?: boolean;
|
|
43
|
+
/**
|
|
44
|
+
* Development output: component names in the compiled code and the extra runtime checks.
|
|
45
|
+
* Set `true` to get development output in a production build, or `false` to get it out of `vite dev`.
|
|
46
|
+
* @default true for `vite dev` (command `serve`), false for `vite build`
|
|
47
|
+
*/
|
|
48
|
+
dev?: boolean;
|
|
49
|
+
/**
|
|
50
|
+
* Run the browser build of ShadowJS under Vitest, instead of the server build that the `node`
|
|
51
|
+
* condition selects. Tests that render on the server (`renderToString`) want `false`.
|
|
52
|
+
* @default true when the Vitest environment is `happy-dom` or `jsdom`, otherwise false
|
|
53
|
+
*/
|
|
54
|
+
domTests?: boolean;
|
|
55
|
+
/**
|
|
56
|
+
* Compiler plugins that run in the build on every module this plugin compiles: `"pre"` plugins
|
|
57
|
+
* (the default) on the syntax tree before the compiler's own passes, `"post"` plugins on the
|
|
58
|
+
* generated code, each group in list order. A plugin can report findings and change the module
|
|
59
|
+
* (strip test attributes, collect translation keys, sort class names); it never reaches the
|
|
60
|
+
* browser. Errors fail the build with the plugin's name and the position in the file; warnings go
|
|
61
|
+
* to Vite's warning log. Only files that `include` matches are compiled, so a plugin sees plain
|
|
62
|
+
* `.ts` modules only when `include` covers them. See `CompilerPlugin` in `@shadow-js/compiler`.
|
|
63
|
+
* @default undefined (no plugins; nothing is added to the build)
|
|
64
|
+
*/
|
|
65
|
+
plugins?: readonly CompilerPlugin[];
|
|
66
|
+
/**
|
|
67
|
+
* Which implementation of the compiler runs. `@shadow-js/compiler` holds three of the same compiler: a Rust addon (about ten times
|
|
68
|
+
* faster on large apps), the same Rust code as WebAssembly, and the TypeScript implementation. `"auto"` uses the fastest one the
|
|
69
|
+
* machine has. `"native"` requires the Rust or the WebAssembly implementation and fails, with the reason, when only TypeScript is
|
|
70
|
+
* available; use it in CI to be sure builds are fast. `"javascript"` uses the TypeScript implementation only, for example to compare
|
|
71
|
+
* outputs. The output is identical in every mode. A module compiled with compiler plugins is answered by the TypeScript
|
|
72
|
+
* implementation in every mode. The environment variable `SHADOW_COMPILER_BACKEND` asks for one for the whole process.
|
|
73
|
+
* @default "auto"
|
|
74
|
+
*/
|
|
75
|
+
compiler?: "auto" | "javascript" | "native";
|
|
76
|
+
}
|
|
77
|
+
/**
|
|
78
|
+
* Creates the Vite plugin that compiles a ShadowJS app's JSX and `useStore` calls with
|
|
79
|
+
* `@shadow-js/compiler`. Add it to the Vite config of every ShadowJS app: it runs before Vite's own
|
|
80
|
+
* TypeScript and JSX handling, so Vite never sees JSX. SSR builds get the server target. It also
|
|
81
|
+
* sets the ShadowJS JSX import source and dedupes `@shadow-js/core` and `@shadow-js/web`. A compile
|
|
82
|
+
* error is reported to Vite with its file, line and column.
|
|
83
|
+
* @param options Include and exclude filters, the runtime module, the dev, HMR and test switches, and
|
|
84
|
+
* the compiler plugins.
|
|
85
|
+
* @returns A Vite plugin named `shadowjs` that runs with `enforce: "pre"`.
|
|
86
|
+
* @throws {TypeError} When `include` or `exclude` is not a `RegExp`, `moduleName` is not a non-empty string, or `plugins` is
|
|
87
|
+
* not a list of valid compiler plugins (a member without a unique `name` or a `transform` function, for example), naming the
|
|
88
|
+
* option. The `transform` hook rethrows any error that is not a `CompileError`, which points at a compiler bug. A `CompileError` goes through Vite's `this.error`
|
|
89
|
+
* instead, which fails the build with the file and position.
|
|
90
|
+
* @example
|
|
91
|
+
* // vite.config.ts
|
|
92
|
+
* import { shadow } from "@shadow-js/vite"; // the default export is the same function
|
|
93
|
+
* export default { plugins: [shadow()] };
|
|
94
|
+
* @see ShadowPluginOptions
|
|
95
|
+
* @since 1.0.0
|
|
96
|
+
*/
|
|
97
|
+
export declare function shadow(options?: ShadowPluginOptions): Plugin;
|
|
98
|
+
//#endregion
|
|
99
|
+
export { shadow as default };
|
|
100
|
+
//# sourceMappingURL=index.d.ts.map
|