@typestyles/vite 0.0.0-unstable.fb509f91ba06 → 0.0.0-unstable.ff74983e3aa5
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/README.md +24 -9
- package/dist/index.cjs +426 -234
- package/dist/index.d.cts +57 -37
- package/dist/index.d.ts +57 -37
- package/dist/index.js +398 -216
- package/package.json +9 -12
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# @typestyles/vite
|
|
2
2
|
|
|
3
|
-
Vite plugin for [typestyles](https://github.com/
|
|
3
|
+
Vite plugin for [typestyles](https://github.com/phthalo-dev/typestyles): style HMR in development, optional zero-runtime CSS extraction in production.
|
|
4
4
|
|
|
5
5
|
TypeStyles works without a bundler plugin — styles inject at runtime on first use. This plugin is optional but recommended for Vite apps: it keeps component state while styles hot-reload, catches duplicate namespace collisions at build time, and can emit a static `typestyles.css` file so production ships without client-side `<style>` injection.
|
|
6
6
|
|
|
@@ -63,13 +63,13 @@ export default defineConfig({
|
|
|
63
63
|
});
|
|
64
64
|
```
|
|
65
65
|
|
|
66
|
-
**3. Link the CSS** in your HTML shell (optional — the plugin
|
|
66
|
+
**3. Link the CSS** in your HTML shell (optional — the plugin injects this during dev and build when extraction is enabled):
|
|
67
67
|
|
|
68
68
|
```html
|
|
69
69
|
<link rel="stylesheet" href="/typestyles.css" />
|
|
70
70
|
```
|
|
71
71
|
|
|
72
|
-
During `vite dev`, styles still inject at runtime and HMR works. During `vite build`, the plugin emits `typestyles
|
|
72
|
+
During `vite dev`, styles still inject at runtime and HMR works, and the dev server serves that stable URL. During `vite build`, the plugin emits a content-hashed asset (Vite's `assetFileNames`, usually `assets/typestyles-<hash>.css`), rewrites the link to that href, and defines `__TYPESTYLES_RUNTIME_DISABLED__`. The hashed URL cache-busts on each deploy. Set `extract.fileName` to a literal such as `typestyles.css` to keep a fixed path.
|
|
73
73
|
|
|
74
74
|
Example app: [`examples/vite-app`](../../examples/vite-app)
|
|
75
75
|
|
|
@@ -99,6 +99,13 @@ typestyles({
|
|
|
99
99
|
/** Default: true — fail the build on duplicate recipe / style namespaces */
|
|
100
100
|
warnDuplicates?: boolean;
|
|
101
101
|
|
|
102
|
+
/**
|
|
103
|
+
* Default: true — fail `vite build` when a local module reachable from the app
|
|
104
|
+
* calls `recipe()` and is missing from the extract entry. Set false to extract
|
|
105
|
+
* a subset on purpose.
|
|
106
|
+
*/
|
|
107
|
+
coverage?: boolean;
|
|
108
|
+
|
|
102
109
|
/**
|
|
103
110
|
* - 'runtime': HMR only, no extraction
|
|
104
111
|
* - 'build': extract on vite build; runtime stays on during vite dev (default when modules resolve)
|
|
@@ -109,7 +116,13 @@ typestyles({
|
|
|
109
116
|
extract?: {
|
|
110
117
|
/** Explicit entry files relative to project root */
|
|
111
118
|
modules?: string[];
|
|
112
|
-
/**
|
|
119
|
+
/**
|
|
120
|
+
* Production CSS path.
|
|
121
|
+
* Omitted: content-hashed asset (`assets/typestyles-<hash>.css`).
|
|
122
|
+
* A literal such as `'typestyles.css'` opts out of hashing.
|
|
123
|
+
* `[name]`, `[hash]`, `[hash:N]`, `[ext]`, and `[extname]` are expanded.
|
|
124
|
+
* Dev always serves the stable unhashed URL.
|
|
125
|
+
*/
|
|
113
126
|
fileName?: string;
|
|
114
127
|
};
|
|
115
128
|
});
|
|
@@ -123,7 +136,7 @@ Use when you have multiple entry files or non-standard paths:
|
|
|
123
136
|
typestyles({
|
|
124
137
|
extract: {
|
|
125
138
|
modules: ['src/styles/tokens.ts', 'src/styles/components.ts'],
|
|
126
|
-
fileName: 'assets/typestyles.css',
|
|
139
|
+
fileName: 'assets/typestyles-[hash].css',
|
|
127
140
|
},
|
|
128
141
|
});
|
|
129
142
|
```
|
|
@@ -140,20 +153,22 @@ Even with a convention entry present, this keeps `<style>` injection in producti
|
|
|
140
153
|
|
|
141
154
|
**HMR:** On each `.ts`/`.tsx` module that registers typestyles APIs, the plugin injects `import.meta.hot` accept/dispose handlers. On dispose, it calls `invalidateKeys` from `typestyles/hmr` so stale rules are removed before the module re-executes. HMR code is only injected during `vite dev`, not in production bundles.
|
|
142
155
|
|
|
143
|
-
**Extraction:** On `vite build`, matching entry modules are bundled and executed in Node via `@typestyles/build-runner`. The collected CSS is emitted as a
|
|
156
|
+
**Extraction:** On `vite build`, matching entry modules are bundled and executed in Node via `@typestyles/build-runner`. The collected CSS is emitted as a content-hashed asset so a new deploy cannot be served with a cached copy of the previous stylesheet. In dev, extraction runs on demand when the browser requests `/typestyles.css` so your `<link>` href works without SPA fallback returning HTML.
|
|
144
157
|
|
|
145
|
-
**Duplicate detection:** The plugin scans every source file for namespace strings (`recipe('button'
|
|
158
|
+
**Duplicate detection:** The plugin scans every source file for namespace strings (`recipe({ name: 'button' })` → `.button-`). Collisions across files fail the build with a clear error.
|
|
146
159
|
|
|
147
160
|
## Verify production output
|
|
148
161
|
|
|
149
|
-
|
|
162
|
+
On `vite build`, the plugin fails if a local module reachable from the app calls `recipe()` and that file is missing from the extract entry. The error names the module and the recipe `name`. Import the module from the convention entry, or set `coverage: false` when the production CSS is meant to omit it.
|
|
163
|
+
|
|
164
|
+
Tokens, themes, and `style()` calls are still execute-and-collect: anything the entry file does not run is omitted. The default build filename includes a content hash. Point `verifyTypestylesBuild` at that file, or set `extract.fileName` to a literal path first:
|
|
150
165
|
|
|
151
166
|
```ts
|
|
152
167
|
import { verifyTypestylesBuild } from '@typestyles/build-runner';
|
|
153
168
|
|
|
154
169
|
verifyTypestylesBuild({
|
|
155
170
|
root: process.cwd(),
|
|
156
|
-
cssFile: 'dist/typestyles
|
|
171
|
+
cssFile: 'dist/assets/typestyles-<hash>.css',
|
|
157
172
|
requiredCssSubstrings: ['.button-base'],
|
|
158
173
|
});
|
|
159
174
|
```
|