@remix-run/assets 0.0.0 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Shopify Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,320 @@
-# Placeholder Package
+# assets
 
-This package is a placeholder published at `0.0.0` to reserve the npm name and configure CI publish permissions.
+Fetch-based server for compiling browser JS/TS assets on demand.
+
+## Features
+
+- **On-Demand Compilation** - Compile browser assets on demand
+- **Custom File Mapping** - Define patterns for mapping public URLs to file paths on disk
+- **Access Control** - Control exactly which files can be served with allow and deny rules
+- **Preloads** - Generate modulepreload URLs for `<link>` tags or `Link` headers
+- **Caching** - Conservative caching by default with stable URLs, ETags, and revalidation
+- **Optional Fingerprinting** - Source-based fingerprinted URLs for long-lived browser caching
+- **Source Maps** - Serve inline or external sourcemaps
+
+## Installation
+
+```sh
+npm i remix
+```
+
+## Usage
+
+Use `createAssetServer` to serve browser modules from a URL namespace in your app.
+
+```ts
+import { createRouter } from 'remix/fetch-router'
+import { createAssetServer } from 'remix/assets'
+
+let assetServer = createAssetServer({
+  fileMap: {
+    '/assets/app/*path': 'app/*path',
+    '/assets/npm/*path': 'node_modules/*path',
+  },
+  allow: ['app/assets/**', 'node_modules/**'],
+})
+
+let router = createRouter()
+
+router.get('/assets/*', ({ request }) => {
+  return assetServer.fetch(request)
+})
+```
+
+This example gives you an `/assets/*` endpoint that serves compiled browser JS modules from `app/assets` and `node_modules`.
+
+## Root Directory
+
+Use `rootDir` to specify the root directory of the asset server, which is used to resolve relative file paths. Defaults to `process.cwd()`.
+
+```ts
+import * as path from 'node:path'
+import { createAssetServer } from 'remix/assets'
+
+let assetServer = createAssetServer({
+  rootDir: path.resolve(import.meta.dirname, '..'),
+  fileMap: {
+    '/assets/app/*path': 'app/*path',
+    '/assets/npm/*path': 'node_modules/*path',
+  },
+  allow: ['app/assets/**', 'node_modules/**'],
+})
+```
+
+## Access Control
+
+You must provide an `allow` list to specify which files are allowed to be served. `deny` is optional and takes precedence over `allow`.
+
+```ts
+import { createAssetServer } from 'remix/assets'
+
+let assetServer = createAssetServer({
+  fileMap: { '/assets/app/*path': 'app/*path' },
+  allow: ['app/assets/**'],
+  deny: ['app/**/*.server.*'],
+})
+```
+
+Rules for `allow` and `deny` are file paths or globs. Relative values are resolved from `rootDir`. Absolute file paths match exactly, and absolute directory paths also match their descendants.
+
+## File Map
+
+Use `fileMap` to map public URLs to file paths on disk. The keys are public URL patterns, and the values are root-relative file path patterns.
+
+```ts
+import { createAssetServer } from 'remix/assets'
+
+let assetServer = createAssetServer({
+  fileMap: {
+    '/assets/app/*path': 'app/*path',
+    '/assets/packages/*path': '../packages/*path',
+  },
+  allow: ['app/assets/**', '../packages/**'],
+})
+```
+
+`fileMap` entries use [`route-pattern`](https://github.com/remix-run/remix/tree/main/packages/route-pattern) syntax for both URL and file patterns. Wildcards must be named, and the same params must appear in both patterns so imports can be rewritten back to public URLs.
+
+### File watching
+
+The file system is watched by default so source changes are picked up without requiring a server restart.
+
+```ts
+import { createAssetServer } from 'remix/assets'
+
+let assetServer = createAssetServer({
+  fileMap: { '/assets/app/*path': 'app/*path' },
+  allow: ['app/assets/**', 'app/node_modules/**'],
+})
+```
+
+When finished with the asset server, call `await assetServer.close()` to clean up the file watcher.
+
+```ts
+await assetServer.close()
+```
+
+You can disable file watching if the files on disk won't change, or if watching is managed at a higher level (e.g. Node's `--watch` flag).
+
+```ts
+import { createAssetServer } from 'remix/assets'
+
+let assetServer = createAssetServer({
+  fileMap: { '/assets/app/*path': 'app/*path' },
+  allow: ['app/assets/**', 'app/node_modules/**'],
+  watch: false,
+})
+```
+
+You can optionally provide an array of glob patterns to the `watch.ignore` option:
+
+```ts
+import { createAssetServer } from 'remix/assets'
+
+let assetServer = createAssetServer({
+  fileMap: { '/assets/app/*path': 'app/*path' },
+  allow: ['app/assets/**', 'app/node_modules/**'],
+  watch: {
+    ignore: ['**/node_modules/**'],
+  },
+})
+```
+
+## Hrefs
+
+Use `assetServer.getHref()` when you need the public URL for a served asset. You can provide a root-relative or absolute file path, or a `file://` URL.
+
+```ts
+let src = await assetServer.getHref('app/assets/entry.tsx')
+// '/assets/app/assets/entry.tsx'
+```
+
+## Preloads
+
+Use `assetServer.getPreloads()` when rendering HTML so you can turn the returned URLs into `<link rel="modulepreload">` tags or `Link` headers for one or more assets and their dependencies. You can provide root-relative or absolute file paths, or `file://` URLs.
+
+```ts
+let preloads = await assetServer.getPreloads(['app/assets/entry.tsx', 'app/assets/search.tsx'])
+// [
+//   '/assets/app/assets/entry.tsx',
+//   '/assets/app/assets/search.tsx',
+//   '/assets/app/assets/utils.ts',
+//   '/assets/npm/@remix-run/component/index.js',
+//   ...etc
+// ]
+```
+
+## Fingerprinting
+
+By default, scripts are served at stable URLs with ETags and `Cache-Control: no-cache`. Responses are cached for the lifetime of the asset server instance.
+
+If you want clients to cache scripts aggressively without revalidation, you can opt into source-based fingerprinting.
+
+```ts
+import { createAssetServer } from 'remix/assets'
+
+let assetServer = createAssetServer({
+  fileMap: { '/assets/app/*path': 'app/*path' },
+  allow: ['app/assets/**'],
+  watch: false,
+  fingerprint: {
+    buildId: process.env.GITHUB_SHA,
+  },
+})
+```
+
+When fingerprinting is enabled, scripts use a `.@<fingerprint>` segment before the file extension and are served with `Cache-Control: public, max-age=31536000, immutable`.
+
+Source fingerprints are based on the original file contents and the build ID. The build ID must change for each deployment so that fingerprinted modules are invalidated together. This fingerprinting strategy assumes that files on disk won't change, so fingerprinting requires `watch: false`.
+
+## Script Options
+
+### Minification
+
+Enable minification with `scripts.minify`:
+
+```ts
+import { createAssetServer } from 'remix/assets'
+
+let assetServer = createAssetServer({
+  fileMap: { '/assets/app/*path': 'app/*path' },
+  allow: ['app/assets/**'],
+  scripts: {
+    minify: true,
+  },
+})
+```
+
+### Target
+
+Use `scripts.target` to lower emitted syntax to a specific ECMAScript version.
+
+```ts
+import { createAssetServer } from 'remix/assets'
+
+let assetServer = createAssetServer({
+  fileMap: { '/assets/app/*path': 'app/*path' },
+  allow: ['app/assets/**'],
+  scripts: {
+    target: 'es2019',
+  },
+})
+```
+
+The default target is `esnext`, which means all syntax is preserved.
+
+### Define
+
+Use `scripts.define` to replace global identifiers with constant expressions.
+
+```ts
+import { createAssetServer } from 'remix/assets'
+
+let assetServer = createAssetServer({
+  fileMap: { '/assets/app/*path': 'app/*path' },
+  allow: ['app/assets/**', 'app/node_modules/**'],
+  scripts: {
+    define: {
+      'process.env.NODE_ENV': '"production"',
+    },
+    minify: true,
+  },
+})
+```
+
+Values are injected exactly as defined, so string literals must include their own quotes, e.g. `process.env.NODE_ENV` must be `"production"` rather than `production`.
+
+### Source Maps
+
+Enable sourcemaps with either `'external'` or `'inline'` using `scripts.sourceMaps`:
+
+```ts
+import { createAssetServer } from 'remix/assets'
+
+let assetServer = createAssetServer({
+  fileMap: { '/assets/app/*path': 'app/*path' },
+  allow: ['app/assets/**'],
+  scripts: {
+    sourceMaps: 'external',
+  },
+})
+```
+
+By default, sourcemap `sources` use URLs so they're presented alongside the compiled output in your browser's developer tools. You can also use file system paths instead with `scripts.sourceMapSourcePaths`:
+
+```ts
+import { createAssetServer } from 'remix/assets'
+
+let assetServer = createAssetServer({
+  fileMap: { '/assets/app/*path': 'app/*path' },
+  allow: ['app/assets/**'],
+  scripts: {
+    sourceMaps: 'inline',
+    sourceMapSourcePaths: 'absolute',
+  },
+})
+```
+
+### External Imports
+
+Use `scripts.external` to leave specific import specifiers unchanged by providing an array of specifiers.
+
+```ts
+import { createAssetServer } from 'remix/assets'
+
+let assetServer = createAssetServer({
+  fileMap: { '/assets/app/*path': 'app/*path' },
+  allow: ['app/assets/**'],
+  scripts: {
+    external: ['my-external-import'],
+  },
+})
+```
+
+## Error Handling
+
+Use `onError` to report unexpected compilation failures and/or return a custom response.
+
+```ts
+import { createAssetServer } from 'remix/assets'
+
+let assetServer = createAssetServer({
+  fileMap: { '/assets/app/*path': 'app/*path' },
+  allow: ['app/assets/**'],
+  onError(error) {
+    console.error('Failed to build client module', error)
+    return new Response('Client module build failed', { status: 500 })
+  },
+})
+```
+
+If `onError` returns nothing, the asset server responds with the default `500 Internal Server Error` response.
+
+## Related Packages
+
+- [`fetch-router`](https://github.com/remix-run/remix/tree/main/packages/fetch-router) - A Fetch-based router that pairs naturally with `assets`
+- [`route-pattern`](https://github.com/remix-run/remix/tree/main/packages/route-pattern) - Route-pattern syntax for URL and route file matching
+
+## License
+
+See [LICENSE](https://github.com/remix-run/remix/blob/main/LICENSE)

package/dist/assets.d.ts

@@ -0,0 +1,3 @@
+export { createAssetServer } from './lib/asset-server.ts';
+export type { AssetServer, AssetServerOptions } from './lib/asset-server.ts';
+//# sourceMappingURL=assets.d.ts.map

package/dist/assets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assets.d.ts","sourceRoot":"","sources":["../src/assets.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAA;AACzD,YAAY,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAA"}

package/dist/assets.js

@@ -0,0 +1 @@
+export { createAssetServer } from "./lib/asset-server.js";

package/dist/lib/access.d.ts

@@ -0,0 +1,10 @@
+type AccessPolicy = {
+    isAllowed(filePath: string): boolean;
+};
+export declare function createAccessPolicy(options: {
+    allow: readonly string[];
+    deny?: readonly string[];
+    rootDir: string;
+}): AccessPolicy;
+export {};
+//# sourceMappingURL=access.d.ts.map

package/dist/lib/access.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"access.d.ts","sourceRoot":"","sources":["../../src/lib/access.ts"],"names":[],"mappings":"AAEA,KAAK,YAAY,GAAG;IAClB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAA;CACrC,CAAA;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE;IAC1C,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;IACxB,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACxB,OAAO,EAAE,MAAM,CAAA;CAChB,GAAG,YAAY,CAaf"}

package/dist/lib/access.js

@@ -0,0 +1,14 @@
+import { createFileMatcher } from "./file-matcher.js";
+export function createAccessPolicy(options) {
+    let allowMatchers = options.allow.map((pattern) => createFileMatcher(pattern, options.rootDir));
+    let denyMatchers = (options.deny ?? []).map((pattern) => createFileMatcher(pattern, options.rootDir));
+    return {
+        isAllowed(filePath) {
+            if (!allowMatchers.some((matcher) => matcher(filePath)))
+                return false;
+            if (denyMatchers.length > 0 && denyMatchers.some((matcher) => matcher(filePath)))
+                return false;
+            return true;
+        },
+    };
+}

package/dist/lib/asset-server.d.ts

@@ -0,0 +1,137 @@
+import type { ChokidarWatcher } from './watch.ts';
+interface AssetServerWatchOptions {
+    /**
+     * Ignore matching glob patterns or file paths. Relative values are resolved
+     * from `rootDir`.
+     */
+    ignore?: readonly string[];
+    /**
+     * Use polling instead of native filesystem events. Defaults to `false`.
+     */
+    poll?: boolean;
+    /**
+     * Polling interval in milliseconds when `poll` is enabled. Defaults to `100`.
+     */
+    pollInterval?: number;
+}
+interface FingerprintOptions {
+    /**
+     * Per-build invalidation token that must change whenever fingerprinted module URLs
+     * should be invalidated together.
+     */
+    buildId: string;
+}
+declare const scriptTargets: readonly ["es2015", "es2016", "es2017", "es2018", "es2019", "es2020", "es2021", "es2022", "es2023", "es2024", "es2025", "es2026", "esnext"];
+export type ScriptsTarget = (typeof scriptTargets)[number];
+export interface AssetServerOptions {
+    /** File patterns keyed by public URL patterns. */
+    fileMap: Readonly<Record<string, string>>;
+    /**
+     * Root directory used to resolve relative file paths. Defaults to `process.cwd()`.
+     */
+    rootDir?: string;
+    /**
+     * Glob patterns or file paths that are allowed to be served. Relative values are resolved from `rootDir`.
+     */
+    allow: readonly string[];
+    /**
+     * Glob patterns or file paths that are denied from being served. Relative values are resolved from `rootDir`.
+     */
+    deny?: readonly string[];
+    /**
+     * Controls optional source-based URL fingerprinting for rewritten import URLs.
+     *
+     * When omitted, all served modules use stable non-fingerprinted URLs with `Cache-Control: no-cache`.
+     * Cannot be used together with active watch mode. Set `watch: false` when fingerprinting.
+     */
+    fingerprint?: FingerprintOptions;
+    /**
+     * Script pipeline configuration. Omit to use defaults.
+     */
+    scripts?: {
+        /**
+         * Source map mode (disabled when omitted).
+         * - `'external'`: serve source maps as separate `.map` files; adds `//# sourceMappingURL=` comment
+         * - `'inline'`: embed source maps as a base64 data URL directly in the JS; no separate `.map` file
+         */
+        sourceMaps?: 'inline' | 'external';
+        /**
+         * Controls the source paths written into source map `sources`.
+         * - `'url'` (default): use the stable server path (e.g. `'/assets/app/entry.ts'`)
+         * - `'absolute'`: use the original filesystem path on disk
+         */
+        sourceMapSourcePaths?: 'url' | 'absolute';
+        /**
+         * Minify emitted modules.
+         */
+        minify?: boolean;
+        /**
+         * Replace global expressions with constant values during transform, e.g.
+         * `{ 'process.env.NODE_ENV': '"production"' }`
+         */
+        define?: Record<string, string>;
+        /**
+         * Lower emitted syntax to a specific ECMAScript target. Omit this option to preserve
+         * modern syntax unless project configuration already requests a lower target.
+         */
+        target?: ScriptsTarget;
+        /** Import specifiers to leave unrewritten (CDN URLs, import map entries, etc.) */
+        external?: string[];
+    };
+    /**
+     * Enable filesystem-backed cache invalidation for long-lived server instances.
+     * Enabled by default. Pass `true` to use the default watcher options, an options
+     * object to customize watcher behavior, or `false` to disable watching.
+     */
+    watch?: boolean | AssetServerWatchOptions;
+    /**
+     * Handles unexpected request-time compilation errors. Return a `Response` to override the
+     * default `500 Internal Server Error` response, or return nothing to use the default.
+     */
+    onError?: (error: unknown) => void | Response | Promise<void | Response>;
+}
+export interface AssetServer {
+    /**
+     * Serves a script request. Returns `Response | null` — null means the request was not
+     * handled by this server, letting the router fall through to a 404.
+     */
+    fetch(request: Request): Promise<Response | null>;
+    /**
+     * Returns the request href for a served module file.
+     */
+    getHref(filePath: string): Promise<string>;
+    /**
+     * Returns preload URLs for one or more served module files, ordered shallowest-first.
+     */
+    getPreloads(filePath: string | readonly string[]): Promise<string[]>;
+    /**
+     * Closes any watcher resources owned by this server instance.
+     */
+    close(): Promise<void>;
+}
+export declare function getInternalChokidarWatcher(assetServer: AssetServer): ChokidarWatcher | undefined;
+export declare function getInternalWatchTargets(assetServer: AssetServer): readonly string[];
+/**
+ * Create an asset server instance
+ *
+ * Compiles TypeScript/JavaScript modules on demand with optional source-based URL
+ * fingerprinting, caching, and configurable file mapping.
+ *
+ * @param options Server configuration
+ * @returns A {@link AssetServer} with `fetch()`, `getHref()`, and `getPreloads()` methods
+ *
+ * @example
+ * ```ts
+ * let assetServer = createAssetServer({
+ *   fileMap: {
+ *     '/assets/app/*path': 'app/*path',
+ *   },
+ *   allow: ['app/**'],
+ * })
+ *
+ * route('/assets/*path', ({ request }) => assetServer.fetch(request))
+ * ```
+ */
+export declare function createAssetServer(options: AssetServerOptions): AssetServer;
+export {};
+//# sourceMappingURL=asset-server.d.ts.map

package/dist/lib/asset-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"asset-server.d.ts","sourceRoot":"","sources":["../../src/lib/asset-server.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAGjD,UAAU,uBAAuB;IAC/B;;;OAGG;IACH,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC1B;;OAEG;IACH,IAAI,CAAC,EAAE,OAAO,CAAA;IACd;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,UAAU,kBAAkB;IAC1B;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,QAAA,MAAM,aAAa,6IAcT,CAAA;AAGV,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAA;AAE1D,MAAM,WAAW,kBAAkB;IACjC,kDAAkD;IAClD,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IACzC;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;OAEG;IACH,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;IACxB;;OAEG;IACH,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACxB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,kBAAkB,CAAA;IAChC;;OAEG;IACH,OAAO,CAAC,EAAE;QACR;;;;WAIG;QACH,UAAU,CAAC,EAAE,QAAQ,GAAG,UAAU,CAAA;QAClC;;;;WAIG;QACH,oBAAoB,CAAC,EAAE,KAAK,GAAG,UAAU,CAAA;QACzC;;WAEG;QACH,MAAM,CAAC,EAAE,OAAO,CAAA;QAChB;;;WAGG;QACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;QAC/B;;;WAGG;QACH,MAAM,CAAC,EAAE,aAAa,CAAA;QACtB,kFAAkF;QAClF,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;KACpB,CAAA;IACD;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,GAAG,uBAAuB,CAAA;IACzC;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GAAG,QAAQ,GAAG,OAAO,CAAC,IAAI,GAAG,QAAQ,CAAC,CAAA;CACzE;AAED,MAAM,WAAW,WAAW;IAC1B;;;OAGG;IACH,KAAK,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAA;IACjD;;OAEG;IACH,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAC1C;;OAEG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;IACpE;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACvB;AAsBD,wBAAgB,0BAA0B,CAAC,WAAW,EAAE,WAAW,GAAG,eAAe,GAAG,SAAS,CAEhG;AAED,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,WAAW,GAAG,SAAS,MAAM,EAAE,CAEnF;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,WAAW,CA4H1E"}