@fastkit/plugboy 1.2.2 → 1.4.0

package/README.md

@@ -145,6 +145,114 @@ export default defineWorkspaceConfig({
 });
 ```
 
+#### Build Target
+
+`target` is passed straight through to tsdown and decides which JavaScript
+syntax is downleveled. Pass a single target, an array of targets, or `false` to
+disable every transformation.
+
+```typescript
+export default defineWorkspaceConfig({
+  // A library expected to run on both Node.js and browsers declares the lower
+  // bound of each: the output satisfies every listed environment.
+  target: ['node20.19', 'chrome111', 'firefox114', 'safari16.4']
+});
+```
+
+Set it in `plugboy.project.ts` to apply one target to every workspace; a
+workspace that declares its own `target` replaces the project value outright
+(target lists are not merged). When neither layer sets it, tsdown falls back to
+the package's `engines.node` field, and applies no transformation at all when
+that field is absent.
+
+Only *syntax* is lowered — runtime APIs (`structuredClone`, `Array#at`, …) are
+never polyfilled. The value also becomes the default for `css.target` below,
+where every non-browser entry of the list is ignored.
+
+#### CSS Options
+
+`css` is passed straight through to tsdown and controls how stylesheets are
+processed and emitted — the output file name, preprocessor options, CSS modules,
+syntax lowering, and so on.
+
+```typescript
+export default defineWorkspaceConfig({
+  css: {
+    // Name of the single emitted stylesheet.
+    fileName: 'my-package.css',
+    // Lower CSS syntax for browsers only, independently of `target`.
+    target: ['chrome111', 'firefox114', 'safari16.4']
+  }
+});
+```
+
+Set it in `plugboy.project.ts` to apply defaults to every workspace; a workspace
+value is shallow-merged over the project one, so it only needs to restate the
+keys it changes.
+
+Plugins may seed defaults here during workspace setup — the vanilla-extract
+plugin, for instance, owns `splitting` and `fileName` so the emitted file matches
+the CSS export plugboy declares. A configured value always wins over a plugin
+default, so check the plugin's documentation before overriding a key it manages.
+
+#### CSS Optimization
+
+`optimizeCSS` applies plugboy's own postcss pass on top of whatever tsdown
+produced: duplicate `@layer` / `@media` blocks are merged, and the selectors
+listed in `combineRules` are combined into a single rule. Pass `false` to disable
+it.
+
+```typescript
+export default defineWorkspaceConfig({
+  optimizeCSS: {
+    combineRules: {
+      rules: [':root']
+    }
+  }
+});
+```
+
+It runs in `writeBundle`, on the stylesheets on disk, so it covers **every**
+stylesheet the build writes — including the ones tsdown's own CSS pipeline emits,
+which it does after every plugin has had its say.
+
+#### Preserved at the top of a stylesheet
+
+Two things tsdown's CSS pipeline would rewrite are restored afterwards, in this
+order, above every rule:
+
+1. **The authored `@layer` order.** lightningcss prunes a name from an
+   `@layer a, b, c;` statement once a block for it appears in the same
+   stylesheet. For a library that is wrong whenever the statement also orders
+   layers owned by *other* packages — the pruned layer's position then depends on
+   where its block happens to land relative to those. plugboy reads the statements
+   before the transform and re-emits them verbatim.
+2. **External `@import`s.** A bare package specifier (e.g.
+   `@import url('material-symbols/rounded.css') layer(...)`) stays external
+   instead of being inlined, so the consumer's bundler resolves it and the
+   imported package's own relative asset URLs keep working.
+
+Both are captured from every stylesheet in the module graph, whether its contents
+were authored or generated by a plugin — vanilla-extract emits its `@layer`
+statements into a virtual module, and those are covered too.
+
+#### One stylesheet per CSS entry
+
+Every entry with `css: true` gets a `./<entry>.css` export, and each of those files
+is guaranteed to exist and to be usable on its own.
+
+With several such entries the build emits one stylesheet per output *chunk*
+(`css.splitting`), which does not line up: CSS reached from more than one entry is
+moved into a shared chunk and emitted under a hashed name that no export points at,
+and an entry whose CSS comes only from there gets no stylesheet at all. plugboy
+rebuilds each entry's stylesheet from its own CSS plus the CSS of every chunk it
+imports, dependencies first, and drops the leftover per-chunk files. Shared CSS is
+duplicated into each entry that needs it, which is what makes a single
+`./<entry>.css` import complete.
+
+This is skipped when `css.inject` is on, since the JavaScript then imports the
+per-chunk stylesheets by name.
+
 ### defineProjectConfig
 
 #### Workspace Management

package/dist/cli.mjs

@@ -1,7 +1,7 @@
-import { i as getWorkspace, t as generateWorkspace } from "./workspace-B66AR1T-.mjs";
+import { i as getWorkspace, t as generateWorkspace } from "./workspace-B6BoRqWL.mjs";
 import { cac } from "cac";
 //#region package.json
-var version = "1.2.2";
+var version = "1.4.0";
 //#endregion
 //#region src/cli.ts
 async function main() {

package/dist/plugboy.d.mts

@@ -559,7 +559,7 @@ type WorkspaceEntries = Record<string, WorkspaceEntry>;
  * @remarks The configuration must be `{ [id]: [Entry setting: }`. `"." ` is treated as a special ID and is the target of the main export.
  */
 type RawWorkspaceEntries = Record<string, RawWorkspaceEntry>;
-declare const TSDOWN_SYNC_OPTIONS: ["define", "skipNodeModulesBundle", "onSuccess", "copy", "deps"];
+declare const TSDOWN_SYNC_OPTIONS: ["define", "skipNodeModulesBundle", "onSuccess", "copy", "deps", "target"];
 type TSDownSyncOption = (typeof TSDOWN_SYNC_OPTIONS)[number];
 interface TSDownSyncOptions extends Pick<UserConfig, TSDownSyncOption> {}
 /**
@@ -617,6 +617,40 @@ interface UserWorkspaceConfig extends TSDownSyncOptions {
    * `stub`.
    */
   copy?: UserConfig['copy'];
+  /**
+   * tsdown's `target` option — the environment(s) the output syntax is
+   * downleveled for.
+   *
+   * @remarks
+   * Inherited from the project configuration when omitted. A value set here
+   * replaces the project default outright (a target list describes one
+   * environment set, so merging the two would be meaningless).
+   *
+   * Note that this only lowers *syntax*; runtime APIs are never polyfilled.
+   * Unset at both layers, tsdown falls back to `engines.node` of the package,
+   * and applies no transformation at all when that field is absent.
+   *
+   * @example `['node20.19', 'chrome111']`
+   */
+  target?: UserConfig['target'];
+  /**
+   * tsdown's `css` option — how stylesheets are processed and emitted.
+   *
+   * @remarks
+   * Shallow-merged over the project configuration, so a workspace only needs to
+   * restate the keys it changes.
+   *
+   * Plugins may seed defaults here during workspace setup (e.g. the
+   * vanilla-extract plugin sets `splitting` / `fileName`, which it needs to own
+   * to keep its CSS pipeline intact). A value declared in the configuration
+   * always wins over such a default — consult the plugin's documentation before
+   * overriding a key it manages.
+   *
+   * `css.target` defaults to {@link UserWorkspaceConfig.target}.
+   *
+   * @see {@link CssOptions}
+   */
+  css?: CssOptions;
   /**
    * CSS optimization options
    *
@@ -631,7 +665,7 @@ interface UserWorkspaceConfig extends TSDownSyncOptions {
 /**
  * Workspace Configuration
  */
-interface ResolvedWorkspaceConfig extends Required<Omit<UserWorkspaceConfig, 'entries' | 'hooks' | 'plugins' | 'dts' | 'publicDir' | 'optimizeCSS' | TSDownSyncOption>>, TSDownSyncOptions {
+interface ResolvedWorkspaceConfig extends Required<Omit<UserWorkspaceConfig, 'entries' | 'hooks' | 'plugins' | 'dts' | 'publicDir' | 'optimizeCSS' | 'css' | TSDownSyncOption>>, TSDownSyncOptions {
   /**
    * Configuration of all entries in the workspace
    *
@@ -659,6 +693,12 @@ interface ResolvedWorkspaceConfig extends Required<Omit<UserWorkspaceConfig, 'en
    * (`true` → `'public'`).
    */
   publicDir: string | false;
+  /**
+   * tsdown's `css` option — how stylesheets are processed and emitted.
+   *
+   * @see {@link CssOptions}
+   */
+  css?: CssOptions;
   /**
    * CSS optimization options
    *
@@ -738,6 +778,17 @@ interface WorkspaceSetupContext {
    * @see {@link NormalizedDTSSettings}
    */
   dts: NormalizedDTSSettings;
+  /**
+   * tsdown's `css` option, seeded from the project and workspace
+   * configurations.
+   *
+   * @remarks
+   * Plugins may extend this during workspace setup, but must merge rather than
+   * assign, and must let the configured value win — a plugin default belongs
+   * *under* `...ctx.css`, never over it.
+   *
+   * @see {@link CssOptions}
+   */
   css?: CssOptions;
   /**
    * CSS optimization options
@@ -863,11 +914,34 @@ interface UserProjectConfig {
    * @see {@link OptimizeCSSOptions}
    */
   optimizeCSS?: OptimizeCSSOptions | boolean;
+  /**
+   * tsdown's `target` option — the environment(s) the output syntax is
+   * downleveled for.
+   *
+   * @remarks
+   * Applies to every workspace in the project. A workspace that declares its
+   * own `target` replaces this value outright (a target list describes one
+   * environment set, so merging the two would be meaningless).
+   *
+   * @example `['node20.19', 'chrome111']`
+   */
+  target?: UserConfig['target'];
+  /**
+   * tsdown's `css` option — how stylesheets are processed and emitted.
+   *
+   * @remarks
+   * Applies to every workspace in the project. A workspace's own `css` is
+   * shallow-merged over this value, so it only needs to restate the keys it
+   * changes.
+   *
+   * @see {@link CssOptions}
+   */
+  css?: CssOptions;
 }
 /**
  * Project Configuration
  */
-interface ResolvedProjectConfig extends Required<Omit<UserProjectConfig, 'scripts' | 'tsconfig' | 'hooks' | 'plugins' | 'dts' | 'optimizeCSS'>> {
+interface ResolvedProjectConfig extends Required<Omit<UserProjectConfig, 'scripts' | 'tsconfig' | 'hooks' | 'plugins' | 'dts' | 'optimizeCSS' | 'target' | 'css'>> {
   /**
    * Workspace script templates list
    * @remarks Used to create a new workspace with the `plugboy gen` CLI command.
@@ -901,6 +975,16 @@ interface ResolvedProjectConfig extends Required<Omit<UserProjectConfig, 'script
    * @see {@link OptimizeCSSOptions}
    */
   optimizeCSS: OptimizeCSSOptions | false;
+  /**
+   * tsdown's `target` option applied to every workspace in the project, unless
+   * the workspace declares its own.
+   */
+  target?: UserConfig['target'];
+  /**
+   * tsdown's `css` option applied to every workspace in the project, with the
+   * workspace's own `css` shallow-merged over it.
+   */
+  css?: CssOptions;
 }
 type ProjectPackageJson = RequiredPackageJSON<ProjectRequiredField>;
 /**

package/dist/plugboy.mjs

@@ -1,2 +1,2 @@
-import { $ as resolveOptimizeCSSOptions, A as resolveRawExposeEntriesSettings, B as resolveBundledConfigOutputFile, C as findProjectPlugin, D as loadProjectConfig, E as isProjectPackageJson, F as getFilename, G as mergeChunkAddons, H as stripDanglingDTSSourceMaps, I as isFileNotFoundException, J as isPromise, K as mergeExternals, L as pathExists, M as findConfig, N as findFile, O as resolveUserProjectConfig, P as getDirname, Q as WORKSPACE_REQUIRED_FIELDS, R as rmrf, S as extractProjectPlugins, T as defineProjectConfig, U as exitHook, V as DANGLING_DTS_SOURCE_MAP_RE, W as collectExternalStringPrefixes, X as PROJECT_REQUIRED_FIELDS, Y as resolveListable, Z as TSDOWN_SYNC_OPTIONS, _ as loadWorkspaceConfig, a as syncWorkspacePackageFields, b as resolveUserWorkspaceConfig, c as Builder, d as getWorkspacePackageJson, et as mergeDTSSettingsList, f as Path, g as isWorkspacePackageJson, h as defineWorkspaceConfig, i as getWorkspace, it as createHooksDefaults, j as copyDirSync, k as exposeEntries, l as findWorkspacePackages, m as resolveUserHooks, n as PlugboyWorkspace, nt as normalizeDTSPreserveTypeTarget, o as PlugboyProject, p as buildHooks, q as mergeNoExternals, r as WORKSPACE_PACKAGE_SYNC_FIELDS, rt as normalizeDTSSettings, s as getProject, t as generateWorkspace, tt as normalizeDTSPreserveTypeSettings, u as getProjectPackageJson, v as resolveRawWorkspaceEntries, w as resolveUserPluginOption, x as definePlugin, y as resolveRawWorkspaceEntry, z as writeFileAtomic } from "./workspace-B66AR1T-.mjs";
+import { $ as resolveOptimizeCSSOptions, A as resolveRawExposeEntriesSettings, B as resolveBundledConfigOutputFile, C as findProjectPlugin, D as loadProjectConfig, E as isProjectPackageJson, F as getFilename, G as mergeChunkAddons, H as stripDanglingDTSSourceMaps, I as isFileNotFoundException, J as isPromise, K as mergeExternals, L as pathExists, M as findConfig, N as findFile, O as resolveUserProjectConfig, P as getDirname, Q as WORKSPACE_REQUIRED_FIELDS, R as rmrf, S as extractProjectPlugins, T as defineProjectConfig, U as exitHook, V as DANGLING_DTS_SOURCE_MAP_RE, W as collectExternalStringPrefixes, X as PROJECT_REQUIRED_FIELDS, Y as resolveListable, Z as TSDOWN_SYNC_OPTIONS, _ as loadWorkspaceConfig, a as syncWorkspacePackageFields, b as resolveUserWorkspaceConfig, c as Builder, d as getWorkspacePackageJson, et as mergeDTSSettingsList, f as Path, g as isWorkspacePackageJson, h as defineWorkspaceConfig, i as getWorkspace, it as createHooksDefaults, j as copyDirSync, k as exposeEntries, l as findWorkspacePackages, m as resolveUserHooks, n as PlugboyWorkspace, nt as normalizeDTSPreserveTypeTarget, o as PlugboyProject, p as buildHooks, q as mergeNoExternals, r as WORKSPACE_PACKAGE_SYNC_FIELDS, rt as normalizeDTSSettings, s as getProject, t as generateWorkspace, tt as normalizeDTSPreserveTypeSettings, u as getProjectPackageJson, v as resolveRawWorkspaceEntries, w as resolveUserPluginOption, x as definePlugin, y as resolveRawWorkspaceEntry, z as writeFileAtomic } from "./workspace-B6BoRqWL.mjs";
 export { Builder, DANGLING_DTS_SOURCE_MAP_RE, PROJECT_REQUIRED_FIELDS, Path, PlugboyProject, PlugboyWorkspace, TSDOWN_SYNC_OPTIONS, WORKSPACE_PACKAGE_SYNC_FIELDS, WORKSPACE_REQUIRED_FIELDS, buildHooks, collectExternalStringPrefixes, copyDirSync, createHooksDefaults, definePlugin, defineProjectConfig, defineWorkspaceConfig, exitHook, exposeEntries, extractProjectPlugins, findConfig, findFile, findProjectPlugin, findWorkspacePackages, generateWorkspace, getDirname, getFilename, getProject, getProjectPackageJson, getWorkspace, getWorkspacePackageJson, isFileNotFoundException, isProjectPackageJson, isPromise, isWorkspacePackageJson, loadProjectConfig, loadWorkspaceConfig, mergeChunkAddons, mergeDTSSettingsList, mergeExternals, mergeNoExternals, normalizeDTSPreserveTypeSettings, normalizeDTSPreserveTypeTarget, normalizeDTSSettings, pathExists, resolveBundledConfigOutputFile, resolveListable, resolveOptimizeCSSOptions, resolveRawExposeEntriesSettings, resolveRawWorkspaceEntries, resolveRawWorkspaceEntry, resolveUserHooks, resolveUserPluginOption, resolveUserProjectConfig, resolveUserWorkspaceConfig, rmrf, stripDanglingDTSSourceMaps, syncWorkspacePackageFields, writeFileAtomic };