tempo-sdk 0.0.4 → 0.0.5

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/package.json CHANGED
@@ -1,17 +1,12 @@
1
1
  {
2
2
  "name": "tempo-sdk",
3
- "version": "0.0.4",
3
+ "version": "0.0.5",
4
4
  "type": "module",
5
- "description": "Tempo SDK — Vite + Next.js plugins for JSX annotation and shared page/storyboard types",
5
+ "description": "Tempo SDK — Vite plugin for JSX annotation and shared page/storyboard types",
6
6
  "exports": {
7
7
  ".": {
8
- "types": "./dist/index.d.ts",
9
- "import": "./dist/index.js"
10
- },
11
- "./nextjs": {
12
- "types": "./dist/nextjs.d.ts",
13
- "import": "./dist/nextjs.js",
14
- "require": "./dist/nextjs.cjs"
8
+ "import": "./dist/index.js",
9
+ "types": "./dist/index.d.ts"
15
10
  }
16
11
  },
17
12
  "files": [
@@ -24,16 +19,7 @@
24
19
  "peerDependencies": {
25
20
  "react": "^18 || ^19",
26
21
  "typescript": "^5.0.0",
27
- "vite": "^5 || ^6 || ^7",
28
- "next": "^13 || ^14 || ^15 || ^16"
29
- },
30
- "peerDependenciesMeta": {
31
- "vite": {
32
- "optional": true
33
- },
34
- "next": {
35
- "optional": true
36
- }
22
+ "vite": "^5 || ^6 || ^7"
37
23
  },
38
24
  "devDependencies": {
39
25
  "@types/node": "^25.0.8",
@@ -45,18 +31,12 @@
45
31
  "vite": "^7.3.1",
46
32
  "vitest": "^4.0.18",
47
33
  "@modules/annotation": "0.0.1",
48
- "@modules/typescript": "0.0.1",
49
- "@modules/file-parser": "0.0.1"
34
+ "@modules/typescript": "0.0.1"
50
35
  },
51
36
  "scripts": {
52
37
  "build": "tsup",
53
38
  "demo": "TEMPO=true pnpm --filter @tempo-modules/vite-annotate-plugin-demo dev",
54
- "demo:nextjs": "TEMPO=true pnpm --filter @tempo-modules/tempo-sdk-nextjs-demo dev",
55
39
  "test": "vitest run",
56
- "test:watch": "vitest",
57
- "test:nextjs:unit": "vitest run nextjs-loader.test.ts nextjs-wrapper.test.ts nextjs-fixtures.test.ts nextjs-published.test.ts",
58
- "test:nextjs:integration": "vitest run nextjs-e2e-correctness.test.ts",
59
- "test:nextjs:production": "vitest run nextjs-production.test.ts",
60
- "test:nextjs": "vitest run nextjs-loader.test.ts nextjs-wrapper.test.ts nextjs-fixtures.test.ts nextjs-published.test.ts nextjs-e2e-correctness.test.ts nextjs-production.test.ts"
40
+ "test:watch": "vitest"
61
41
  }
62
42
  }
package/README.md DELETED
@@ -1,272 +0,0 @@
1
- # tempo-sdk
2
-
3
- Tempo's JSX-annotation plugins for Vite and Next.js. At build time, every JSX
4
- element in your codebase gets `data-tempo-*` attributes that map the rendered
5
- DOM back to the exact source-file location that produced it. Tempo's design
6
- surface uses these attributes to navigate from a clicked element to its source.
7
-
8
- This package ships two plugins from one workspace:
9
-
10
- - **`tempo-sdk`** — Vite plugin (`tempoVitePlugin`)
11
- - **`tempo-sdk/nextjs`** — Next.js plugin (`tempoNextjsPlugin`)
12
-
13
- Both produce byte-identical `data-tempo-*` output, so downstream consumers
14
- (`source-editor.ts`, `frame-preload.ts`) work the same regardless of which
15
- framework the user's project is on.
16
-
17
- ---
18
-
19
- ## Next.js usage
20
-
21
- ### 1. Install
22
-
23
- In a workspace package:
24
-
25
- ```jsonc
26
- {
27
- "dependencies": { "tempo-sdk": "workspace:*" }
28
- }
29
- ```
30
-
31
- In an external project: `pnpm add tempo-sdk` (or your package manager's equivalent).
32
-
33
- ### 2. Wrap `next.config`
34
-
35
- CommonJS (`next.config.js`):
36
-
37
- ```js
38
- const tempoNextjsPlugin = require("tempo-sdk/nextjs");
39
-
40
- module.exports = tempoNextjsPlugin()({
41
- reactStrictMode: true,
42
- // ...rest of your existing config
43
- });
44
- ```
45
-
46
- ESM (`next.config.mjs` / `next.config.ts`):
47
-
48
- ```ts
49
- import tempoNextjsPlugin from "tempo-sdk/nextjs";
50
-
51
- export default tempoNextjsPlugin()({
52
- reactStrictMode: true,
53
- });
54
- ```
55
-
56
- ### 3. Set the `TEMPO` env var when launching dev
57
-
58
- ```bash
59
- TEMPO=true next dev # Turbopack (Next.js 16+ default)
60
- TEMPO=true next dev --webpack # Webpack mode
61
- ```
62
-
63
- Without `TEMPO` set, the plugin is a complete no-op. You can leave
64
- `tempoNextjsPlugin()` in `next.config.js` permanently — there is zero overhead
65
- in normal dev. Tempo's start script sets `TEMPO=true` automatically when
66
- launching the project under Tempo.
67
-
68
- ### 4. App Router — that's it
69
-
70
- The loader auto-injects `<meta name="tempo-project-root">` into the first JSX
71
- `<head>` it sees (typically `app/layout.tsx`). Every JSX element in your project
72
- gets `data-tempo-filepath`, `data-tempo-position`, `data-tempo-modifiedts`, and
73
- `data-tempo-supports-*` attributes baked into the SWC-compiled output.
74
-
75
- Example rendered HTML:
76
-
77
- ```html
78
- <button
79
- data-tempo-filepath="components/Button.tsx"
80
- data-tempo-position="142"
81
- data-tempo-modifiedts="1708900000000"
82
- data-tempo-supports-children="true"
83
- >
84
- Click me
85
- </button>
86
-
87
- <head>
88
- <meta name="tempo-project-root" content="/abs/path/to/project" />
89
- </head>
90
- ```
91
-
92
- ### 5. Pages Router — one extra line in `_document.tsx`
93
-
94
- `<Head>` from `next/document` is a **custom** React component (capital H), not
95
- intrinsic JSX `<head>` (lowercase), so auto-inject doesn't fire there. Add the
96
- project-root meta manually:
97
-
98
- ```tsx
99
- // pages/_document.tsx
100
- import { Html, Head, Main, NextScript } from "next/document";
101
- import { tempoProjectRoot } from "tempo-sdk/nextjs";
102
-
103
- export default function Document() {
104
- return (
105
- <Html>
106
- <Head>
107
- <meta name="tempo-project-root" content={tempoProjectRoot()} />
108
- </Head>
109
- <body>
110
- <Main />
111
- <NextScript />
112
- </body>
113
- </Html>
114
- );
115
- }
116
- ```
117
-
118
- `tempoProjectRoot()` returns the same canonical root the loader uses for
119
- `data-tempo-filepath`, so paths reconstruct correctly.
120
-
121
- ### Options
122
-
123
- All optional:
124
-
125
- ```js
126
- tempoNextjsPlugin({
127
- autoInjectRootMeta: false, // disable head meta auto-inject
128
- productionBuild: true, // run in `next build` too (rare)
129
- computeAnnotatedPropsModule: "./tempo-strategy.js", // custom prop-computation
130
- })(nextConfig);
131
- ```
132
-
133
- `computeAnnotatedPropsModule` is a path (not a function) because Turbopack
134
- requires loader options to be JSON-serializable. The module's default export
135
- must be a function `(info, filepath, modifiedtsMs) => Record<string, PropValue>`.
136
-
137
- ### Composing with other wrappers (`@next/mdx`, etc.)
138
-
139
- `tempoNextjsPlugin` follows the `@next/mdx` higher-order-config pattern, so it
140
- composes naturally:
141
-
142
- ```js
143
- const tempoNextjsPlugin = require("tempo-sdk/nextjs");
144
- const withMDX = require("@next/mdx")();
145
-
146
- module.exports = tempoNextjsPlugin()(
147
- withMDX({ reactStrictMode: true })
148
- );
149
- ```
150
-
151
- `tempoNextjsPlugin` should be the **outermost** wrapper so its webpack/turbopack
152
- chaining sees the inner wrappers' contributions.
153
-
154
- ### Supported Next.js versions
155
-
156
- | Next.js | Webpack | Turbopack | Notes |
157
- |---|---|---|---|
158
- | 16.x | `--webpack` flag | default | Validated end-to-end |
159
- | 15.3 – 15.x | default | `--turbo` flag | Wrapper writes to `turbopack.*` |
160
- | 13.0 – 15.2 | default | `--turbo` flag | Wrapper writes to `experimental.turbo.*` |
161
- | 12.x | default | n/a | Webpack only; turbopack field omitted |
162
- | < 12 | n/a | n/a | Out of scope |
163
-
164
- The wrapper detects the version via `next/package.json` and writes to the
165
- correct field automatically.
166
-
167
- ---
168
-
169
- ## Vite usage
170
-
171
- ```ts
172
- // vite.config.ts
173
- import { defineConfig } from "vite";
174
- import react from "@vitejs/plugin-react";
175
- import { tempoVitePlugin } from "tempo-sdk";
176
-
177
- export default defineConfig({
178
- plugins: [tempoVitePlugin(), react()],
179
- });
180
- ```
181
-
182
- Same `TEMPO` env-var gating, same `data-tempo-*` output as the Next.js plugin.
183
- The Vite plugin additionally exposes an `/__tempo/errors` SSE endpoint for
184
- streaming compile errors to the design surface — see `SPEC.md` for the full
185
- design.
186
-
187
- ---
188
-
189
- ## How it works
190
-
191
- The Next.js plugin is a webpack-compatible loader (`nextjs-loader.cjs`) plus a
192
- higher-order config wrapper (`tempoNextjsPlugin`) that registers the loader for
193
- both Webpack and Turbopack from a single user-facing entrypoint.
194
-
195
- The flow per source file:
196
-
197
- 1. Resource gating — `.tsx`/`.jsx` only, exclude `node_modules`, require
198
- `process.env.TEMPO`.
199
- 2. Read mtime via `fs.statSync`.
200
- 3. Compute project-relative filepath via `path.relative(rootContext, …)`.
201
- 4. Call `annotateFile` from `@modules/annotation` with a callback that returns
202
- the `data-tempo-*` props for each JSX element. The walker visits every
203
- `JSXElement`, fragments are skipped, and props are inserted as JSX
204
- attribute strings at the end of each opening tag.
205
- 5. If the file contains an intrinsic JSX `<head>`, splice
206
- `<meta name="tempo-project-root" content="…" />` into the post-annotation
207
- source. The injected meta does not itself carry `data-tempo-*` attrs (it has
208
- no source location), which keeps every other element's `data-tempo-position`
209
- pointing at the byte offset of `<` in the on-disk source file.
210
- 6. Return the annotated source. Errors at any step cause the loader to return
211
- the original source unchanged — `correct or untouched, always`.
212
-
213
- The `tempoNextjsPlugin` wrapper:
214
-
215
- - Adds an `enforce: "pre"` rule under `config.module.rules` for Webpack
216
- (`/.(tsx|jsx)$/`).
217
- - Adds a `*.{tsx,jsx}` rule under `nextConfig.turbopack.rules` for Turbopack
218
- with `condition: { all: [{ not: "foreign" }, "development"] }` (excludes
219
- node_modules / Next internals AND production builds).
220
- - Chains an existing user-supplied `webpack(config, options)` function and
221
- merges with any existing `turbopack.rules` so other plugins are preserved.
222
- - No-ops entirely when `process.env.TEMPO` is not set.
223
-
224
- See `SPEC_NEXTJS.md` for the complete design specification.
225
-
226
- ---
227
-
228
- ## Demo
229
-
230
- ```bash
231
- pnpm --filter @tempo-modules/tempo-sdk-nextjs-demo dev # Turbopack on :3477
232
- pnpm --filter @tempo-modules/tempo-sdk-nextjs-demo dev:webpack # Webpack on :3478
233
- ```
234
-
235
- Then:
236
-
237
- ```bash
238
- curl -s localhost:3477/ | grep -oE 'data-tempo-filepath="[^"]+"' | sort -u
239
- ```
240
-
241
- Should print one line per source file rendered on the home page.
242
-
243
- ---
244
-
245
- ## Tests
246
-
247
- ```bash
248
- pnpm test # all 308 tests across both plugins
249
- pnpm test:nextjs # 175 Next.js tests (~24s)
250
- pnpm test:nextjs:unit # fast unit tests, no servers
251
- pnpm test:nextjs:integration # live `next dev` against demo (Turbopack + Webpack)
252
- pnpm test:nextjs:production # `next build` correctness (no annotations in prod)
253
- ```
254
-
255
- Test layers:
256
-
257
- | File | Tests | Coverage |
258
- |---|---|---|
259
- | `nextjs-loader.test.ts` | 41 | Loader function — file filtering, default strategy, auto-inject, error handling |
260
- | `nextjs-wrapper.test.ts` | 26 | `tempoNextjsPlugin` — webpack chaining, turbopack merging, version detection, options |
261
- | `nextjs-fixtures.test.ts` | 40 | Project shapes — App/Pages Router, server/client components, all routing types |
262
- | `nextjs-published.test.ts` | 14 | Built `dist/*.cjs` and `dist/*.js` — CJS callable, ESM imports, parity |
263
- | `nextjs-production.test.ts` | 6 | `next build` produces zero `data-tempo-*` attributes |
264
- | `nextjs-e2e-correctness.test.ts` | — | Live `next dev` against demo (both bundlers); every recorded `data-tempo-position` actually points at `<` in the on-disk source file |
265
-
266
- ---
267
-
268
- ## Related docs
269
-
270
- - `SPEC.md` — Vite plugin specification
271
- - `SPEC_NEXTJS.md` — Next.js plugin specification
272
- - `SPEC_TSC.md` — TypeScript type-analyzer (used by both plugins for `data-tempo-supports-*`)