@remix-run/assets 0.0.0 → 0.2.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,326 @@
-# 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 and CSS assets on demand.
+
+## Features
+
+- **On-Demand Compilation** - Compile browser scripts and styles 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 preload URLs for scripts and styles based on imports
+- **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 JS/TS and CSS assets 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 assets 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">`, stylesheet preload 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/ui/index.js',
+//   ...etc
+// ]
+```
+
+## Fingerprinting
+
+By default, assets 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 assets 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, assets 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 assets are invalidated together. This fingerprinting strategy assumes that files on disk won't change, so fingerprinting requires `watch: false`.
+
+## Target
+
+Use `target` to lower emitted syntax to a specific browser support policy and/or ECMAScript version.
+
+```ts
+import { createAssetServer } from 'remix/assets'
+
+let assetServer = createAssetServer({
+  fileMap: { '/assets/app/*path': 'app/*path' },
+  allow: ['app/assets/**'],
+  target: {
+    chrome: '109',
+    ios: '15.6',
+    es: '2020',
+  },
+})
+```
+
+Supported target options are `chrome`, `firefox`, `safari`, `edge`, `opera`, `ios`, `samsung`, and `es` (ECMAScript version).
+
+### Source Maps
+
+Enable sourcemaps with either `'external'` or `'inline'` using `sourceMaps`:
+
+```ts
+import { createAssetServer } from 'remix/assets'
+
+let assetServer = createAssetServer({
+  fileMap: { '/assets/app/*path': 'app/*path' },
+  allow: ['app/assets/**'],
+  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 `sourceMapSourcePaths`:
+
+```ts
+import { createAssetServer } from 'remix/assets'
+
+let assetServer = createAssetServer({
+  fileMap: { '/assets/app/*path': 'app/*path' },
+  allow: ['app/assets/**'],
+  sourceMaps: 'inline',
+  sourceMapSourcePaths: 'absolute',
+})
+```
+
+### Minification
+
+Enable minification with `minify`:
+
+```ts
+import { createAssetServer } from 'remix/assets'
+
+let assetServer = createAssetServer({
+  fileMap: { '/assets/app/*path': 'app/*path' },
+  allow: ['app/assets/**'],
+  minify: true,
+})
+```
+
+## Script Options
+
+### 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"',
+    },
+  },
+})
+```
+
+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`.
+
+### 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'],
+  },
+})
+```
+
+## CSS Imports
+
+Relative CSS `@import` rules are rewritten to asset server URLs. External `@import` URLs are left unchanged automatically. `url()` references are preserved as authored.
+
+```css
+/* Rewritten to asset server URL: */
+@import './reset.css';
+/* External URL: */
+@import 'https://fonts.googleapis.com/css2?family=Inter';
+```
+
+## 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 assets', error)
+    return new Response('Client asset 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,139 @@
+import type { AssetTarget } from './target.ts';
+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 asset URLs
+     * should be invalidated together.
+     */
+    buildId: string;
+}
+type AssetSourceMaps = 'inline' | 'external';
+type AssetSourceMapSourcePaths = 'url' | 'absolute';
+interface AssetServerScriptOptions {
+    /**
+     * Replace global expressions with constant values during transform, e.g.
+     * `{ 'process.env.NODE_ENV': '"production"' }`
+     */
+    define?: Record<string, string>;
+    /** Import specifiers to leave unrewritten (CDN URLs, import map entries, etc.) */
+    external?: string[];
+}
+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 asset URLs.
+     *
+     * When omitted, all served assets 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;
+    /**
+     * Shared compatibility target for scripts and styles. Browser targets apply to both
+     * pipelines, and `es` only affects scripts.
+     */
+    target?: AssetTarget;
+    /**
+     * Source map mode for scripts and styles.
+     * - `'external'`: serve source maps as separate `.map` files
+     * - `'inline'`: embed source maps as a base64 data URL in the compiled asset
+     */
+    sourceMaps?: AssetSourceMaps;
+    /**
+     * Source path strategy for 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?: AssetSourceMapSourcePaths;
+    /**
+     * Minification setting for emitted scripts and styles.
+     */
+    minify?: boolean;
+    /**
+     * Script-only configuration.
+     */
+    scripts?: AssetServerScriptOptions;
+    /**
+     * 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 or style 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 asset file.
+     */
+    getHref(filePath: string): Promise<string>;
+    /**
+     * Returns preload URLs for one or more served asset 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 scripts and CSS styles 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":"AAYA,OAAO,KAAK,EAAE,WAAW,EAA6C,MAAM,aAAa,CAAA;AAEzF,OAAO,KAAK,EAAsB,eAAe,EAAE,MAAM,YAAY,CAAA;AAErE,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,KAAK,eAAe,GAAG,QAAQ,GAAG,UAAU,CAAA;AAC5C,KAAK,yBAAyB,GAAG,KAAK,GAAG,UAAU,CAAA;AAEnD,UAAU,wBAAwB;IAChC;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC/B,kFAAkF;IAClF,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;CACpB;AAID,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;;;OAGG;IACH,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB;;;;OAIG;IACH,UAAU,CAAC,EAAE,eAAe,CAAA;IAC5B;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,yBAAyB,CAAA;IAChD;;OAEG;IACH,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB;;OAEG;IACH,OAAO,CAAC,EAAE,wBAAwB,CAAA;IAClC;;;;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;AAuBD,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,CAqN1E"}