@pracht/vite-plugin 0.7.6 → 0.9.0

package/README.md

@@ -56,12 +56,11 @@ pracht({
 Keep it opt-in for now: it is best suited to SSR-heavy pages with large static
 DOM subtrees and should be benchmarked against your app before enabling broadly.
 
-## TSRX (`.tsrx`) Support
+## Additional Route Extensions
 
-`.tsrx` modules — TSRX/Ripple-flavoured Preact components — are supported out
-of the box. Bring your own
-[`@tsrx/vite-plugin-preact`](https://github.com/Ripple-TS/ripple) and add it to
-your `plugins` array alongside `pracht()`:
+Use `additionalExtensions` when a Vite plugin compiles route or shell modules
+with another file extension. For example, TSRX can use the explicit generic
+configuration (while remaining implicitly supported for compatibility):
 
 ```ts
 // vite.config.ts
@@ -70,13 +69,28 @@ import { pracht } from "@pracht/vite-plugin";
 import { tsrxPreact } from "@tsrx/vite-plugin-preact";
 
 export default defineConfig({
-  plugins: [tsrxPreact(), pracht()],
+  plugins: [tsrxPreact(), pracht({ additionalExtensions: [".tsrx"] })],
 });
 ```
 
-The pracht plugin globs `.tsrx` files alongside `.tsx` for routes and shells
-(both manifest- and pages-router modes), and its server-only export stripping
-pass treats them the same way — no separate pracht option is required.
+Extensions must be dot-prefixed. Pracht discovers configured extensions in
+route and shell directories for both manifest and pages-router modes and strips
+server-only route exports from client bundles. Vite-scannable component formats
+join initial dependency scanning automatically; other format plugins must opt
+their extension into Vite's dependency optimizer. The companion plugin remains
+responsible for compiling the file format, and the app should provide any
+ambient TypeScript module declaration that format requires. Keep the array
+inline or in a directly referenced `const` for complete CLI verification;
+dynamic expressions still build but produce a verification warning.
+
+Configured formats are treated as potentially head-bearing even when their raw
+source has no JavaScript `head()` export. The companion transform may synthesize
+that export from frontmatter or other custom syntax, so loaderless client
+navigation conservatively keeps its route-state request.
+
+Existing `.tsrx` routes and shells remain discovered without
+`additionalExtensions`, and Pracht keeps its ambient `.tsrx` declaration so a
+compatible CLI patch cannot strand applications on the previous plugin minor.
 
 ## Peer Dependencies
 
@@ -86,3 +100,11 @@ Target-specific Vite plugins (e.g. `@cloudflare/vite-plugin`) are pulled in by
 the adapter package you install (`@pracht/adapter-cloudflare`,
 `@pracht/adapter-vercel`, etc.). The default path uses `@pracht/adapter-node`,
 which ships as a dependency of this package.
+
+Custom adapters can expose two separate plugin hooks on `PrachtAdapter`:
+
+- `vitePlugins()` for the platform's normal development and build integration.
+- `graphVitePlugins()` for metadata-only CLI servers. This optional hook must
+  not start runtimes, listeners, persistent workers, or debuggers; use it only
+  for safe resolvers or platform-module stubs. When omitted, graph commands
+  load no adapter-contributed plugins.

package/dist/index.d.mts

@@ -70,6 +70,13 @@ interface PrachtAdapter {
    * Returned plugins are appended to the plugin array returned by `pracht()`.
    */
   vitePlugins?(): Plugin[];
+  /**
+   * Vite plugins that can safely run in the CLI's graph-only server. These
+   * plugins may provide runtime-module stubs or other metadata-only support,
+   * but must not start deployment runtimes, listeners, or persistent workers.
+   * When omitted, graph commands load no adapter-contributed plugins.
+   */
+  graphVitePlugins?(): Plugin[];
   /**
    * If true, the adapter owns dev-server request handling and the vite-plugin
    * will not install its own SSR middleware. Used when the adapter contributes
@@ -84,6 +91,18 @@ interface PrachtAdapter {
    * into the server output.
    */
   edge?: boolean;
+  /**
+   * If true, the adapter produces a pure static export with no server at
+   * runtime (e.g. `@pracht/adapter-static`). Production builds then define
+   * `__PRACHT_STATIC_TARGET__` as `true`, which switches the client router's
+   * route-state fetching from the live `x-pracht-route-state-request`
+   * endpoint to the serialized `/_pracht/state/…` files that `pracht build`
+   * emits. Dev servers keep the live endpoint (the flag only applies to
+   * builds). Custom static targets must also expose the static artifact hooks
+   * generated by `@pracht/adapter-static`; the CLI fails when a configured
+   * not-found or fallback artifact cannot be rendered.
+   */
+  staticTarget?: boolean;
 }
 //#endregion
 //#region src/plugin-options.d.ts
@@ -103,6 +122,19 @@ interface PrachtLlmsTxtOptions {
   origin?: string;
   /** Sections to emit. Defaults to ["pages", "api", "capabilities"]. */
   include?: LlmsTxtSection[];
+  /**
+   * Route/API path patterns to leave out, using the same segment globs as
+   * `defineApp({ constraints })` (`*` = one segment, trailing `**` = the
+   * rest). llms.txt invites agents to fetch every URL it lists, so exclude
+   * anything an anonymous agent cannot use — pages behind an auth middleware,
+   * internal tooling, deliberate error routes. Capabilities are matched by
+   * their dispatch path (`/api/capabilities/**`).
+   *
+   * ```ts
+   * llmsTxt: { exclude: ["/dashboard", "/admin/**"] }
+   * ```
+   */
+  exclude?: string[];
 }
 interface PrachtPluginOptions {
   appFile?: string;
@@ -111,6 +143,14 @@ interface PrachtPluginOptions {
   middlewareDir?: string;
   apiDir?: string;
   serverDir?: string;
+  /**
+   * Additional dot-prefixed route and shell module extensions to discover,
+   * such as `[".vue"]`. Register the Vite plugin that transforms the format
+   * separately; Pracht only discovers the modules and applies its route
+   * client/server handling. Defaults to no additional extensions. `.tsrx`
+   * remains discovered without configuration for backward compatibility.
+   */
+  additionalExtensions?: readonly string[];
   /**
    * Directory containing island components hydrated on
    * `hydration: "islands"` routes. Defaults to "/src/islands".
@@ -174,6 +214,8 @@ declare function createPrachtIslandsClientModuleSource(options?: PrachtPluginOpt
 declare function createPrachtServerModuleSource(options?: PrachtPluginOptions, buildOptions?: {
   root?: string;
   isBuild?: boolean;
+  base?: string;
+  configuredBase?: string;
 }): string;
 declare function createPrachtRegistryModuleSource(options?: PrachtPluginOptions): string;
 //#endregion