ayo/wcb
1
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 5

docs: add distPaths() section to cem-plugin guide

Browse source
This commit is contained in:
ayo 2026-07-25 09:37:02 +02:00
parent d97f7762cd
commit 54d62ff080
2 changed files with 23 additions and 21 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
.gitignore vendored
View file

@ -25,3 +25,6 @@ storybook/custom-elements.json
# so `html.customData` in .vscode/settings.json can resolve it
vscode.html-custom-data.json
vscode.css-custom-data.json
# `cem analyze` outputs using `wcb` plugins
.wcb

41
docs/src/content/docs/guides/cem-plugin.mdx
View file

@ -49,12 +49,25 @@ Then run the analyzer:
npx cem analyze
```
<Aside type="caution" title="Publishing a package? Point the manifest at your built files">
The analyzer stamps each module's `path` with the exact file it scanned —
so with `globs: ['src/**/*.ts']` every `path` in `custom-elements.json` is a
`.ts` source file. Most packages publish only their built `dist/` output
(and can't `import` a `.ts` at runtime anyway), so a consumer reading that
manifest resolves paths that aren't in the tarball.
<Aside type="caution" title="LOOK OUT! `cem analyze` fails by hanging, not by erroring">
Run it **from the directory holding your config and a `package.json`**. Two
things make it appear to do nothing, neither of which prints an error:
- **No config found**: it falls back to a default glob of
`**/*.{js,ts,tsx}`, which does _not_ exclude `node_modules`. In a real
project that is tens of thousands of files through the TypeScript parser.
- **No `package.json` in the directory**: it hangs outright.
With globs scoped to your source it should finish in well under a second.
</Aside>
### Prepare to publish a package with `distPaths()`
The analyzer stamps each module's `path` with the exact file it scanned —
so with `globs: ['src/**/*.ts']` every `path` in `custom-elements.json` is a
`.ts` source file. Most packages publish only their built `dist/` output
(and can't `import` a `.ts` at runtime anyway), so a consumer reading that
manifest resolves paths that aren't in the tarball.
Add `distPaths()` after `wcbStaticProps()` to rewrite those paths to the
built output. Zero-config it maps `src/` → `dist/` and TypeScript extensions
@ -70,26 +83,12 @@ export default {
}
```
For a different layout, override `rootDir` / `outDir` (named to mirror
`tsconfig`): `distPaths({ rootDir: 'lib', outDir: 'dist/esm' })`. Run
For a different layout, override `rootDir` / `outDir`: `distPaths({ rootDir: 'lib', outDir: 'dist/esm' })`. Run
`cem analyze` **after** your build so the `dist/` files it points at exist.
Not publishing the manifest — e.g. a local Storybook or editor setup over
your own source — needs none of this.
</Aside>
<Aside type="caution" title="LOOK OUT! `cem analyze` fails by hanging, not by erroring">
Run it **from the directory holding your config and a `package.json`**. Two
things make it appear to do nothing, neither of which prints an error:
- **No config found**: it falls back to a default glob of
`**/*.{js,ts,tsx}`, which does _not_ exclude `node_modules`. In a real
project that is tens of thousands of files through the TypeScript parser.
- **No `package.json` in the directory**: it hangs outright.
With globs scoped to your source it should finish in well under a second.
</Aside>
## What it produces