remix 3.0.0-beta.9 → 3.0.0-rc.2

package/src/assets/README.md

@@ -6,11 +6,11 @@ Fetch-based server for compiling browser assets on demand.
 
 - **On-Demand Compilation** - Compile browser scripts and styles on demand
 - **File Serving** - Serve configured file assets like images and fonts with optional transforms
-- **Custom File Mapping** - Define patterns for mapping public URLs to file paths on disk
 - **Access Control** - Control exactly which files and packages can be served
 - **Preloads** - Generate preload URLs for scripts and styles based on imports
+- **Inspection** - List browser-reachable assets and explain URL-to-file mappings
 - **Caching** - Conservative caching by default with stable URLs, ETags, and revalidation
-- **Optional Fingerprinting** - Source-based fingerprinted URLs for long-lived browser caching
+- **Optional Fingerprinting** - Content-based fingerprinted URLs for long-lived browser caching
 - **Source Maps** - Serve inline or external sourcemaps
 - **Hot Module Reloading** - Handle live code updates in development
 - **Script Loaders** - Post-process compiled JavaScript with Node-compatible loaders
@@ -21,6 +21,12 @@ Fetch-based server for compiling browser assets on demand.
 npm i remix
 ```
 
+The optional image transform examples also use Sharp:
+
+```sh
+npm i sharp
+```
+
 ## Usage
 
 Use `createAssetServer` to serve browser assets from a URL namespace in your app.
@@ -31,10 +37,6 @@ import { createAssetServer } from 'remix/assets'
 
 let assetServer = createAssetServer({
   basePath: '/assets',
-  fileMap: {
-    '/app/*path': 'app/*path',
-    '/npm/*path': 'node_modules/*path',
-  },
   allowFiles: ['app/routes.ts', 'app/**/public/**'],
   allowPackages: ['remix'],
   files: {
@@ -51,6 +53,64 @@ router.get('/assets/*', ({ request }) => {
 
 This example gives you an `/assets/*` endpoint that serves compiled browser source from `public/` directories throughout `app/` and from the `remix` package.
 
+## Shared Configuration
+
+Keep JSON-compatible asset mapping, access, and file-type settings in `remix.json` so the running
+server and Remix CLI use the same configuration:
+
+```jsonc
+{
+  "$schema": "./node_modules/remix/schema/remix.json",
+  "assets": {
+    "basePath": "/assets",
+    "mounts": {
+      "app": "app",
+      "npm": "node_modules",
+    },
+    "allowFiles": ["app/routes.ts", "app/**/public/**"],
+    "allowPackages": ["remix"],
+    "denyFiles": ["app/**/*.test.*"],
+    "files": {
+      "extensions": [".svg", ".png", ".jpg", ".woff2"],
+    },
+  },
+}
+```
+
+Load it from application code and add runtime-only behavior there:
+
+```ts
+import { createAssetServer, defineFileTransform } from 'remix/assets'
+import { loadConfig } from 'remix/cli'
+import sharp from 'sharp'
+
+let config = await loadConfig(import.meta.dirname)
+if (config.assets === undefined) throw new Error('Missing assets configuration')
+if (config.assets.files === undefined) throw new Error('Missing asset file configuration')
+
+let assetServer = createAssetServer({
+  ...config.assets,
+  files: {
+    ...config.assets.files,
+    transforms: {
+      webp: defineFileTransform({
+        extensions: ['.png', '.jpg'],
+        async transform(bytes) {
+          return {
+            content: await sharp(bytes).webp({ quality: 80 }).toBuffer(),
+            extension: '.webp',
+          }
+        },
+      }),
+    },
+  },
+})
+```
+
+`loadConfig()` accepts either a config file or a directory. When given a directory, it searches
+upward for the nearest `remix.json`. Run `remix assets` to list reachable files, or
+`remix assets inspect <url-or-file>` to inspect one mapping and its access decision.
+
 ## 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()`.
@@ -62,10 +122,6 @@ import { createAssetServer } from 'remix/assets'
 let assetServer = createAssetServer({
   rootDir: path.resolve(import.meta.dirname, '..'),
   basePath: '/assets',
-  fileMap: {
-    '/app/*path': 'app/*path',
-    '/npm/*path': 'node_modules/*path',
-  },
   allowFiles: ['app/routes.ts', 'app/**/public/**'],
   allowPackages: ['remix'],
 })
@@ -80,10 +136,6 @@ import { createAssetServer } from 'remix/assets'
 
 let assetServer = createAssetServer({
   basePath: '/assets',
-  fileMap: {
-    '/app/*path': 'app/*path',
-    '/npm/*path': 'node_modules/*path',
-  },
   allowFiles: ['app/routes.ts', 'app/**/public/**'],
   allowPackages: ['remix'],
   denyFiles: ['app/**/*.server.*'],
@@ -92,27 +144,27 @@ let assetServer = createAssetServer({
 
 Values for `allowFiles` and `denyFiles` are file paths or globs. Relative values are resolved from `rootDir`. Absolute file paths match exactly, and absolute directory paths also match their descendants.
 
-Values for `allowPackages` are exact package names. Dependencies and installed optional dependencies of packages in `allowPackages` are also allowed automatically. Peer dependencies must be listed explicitly if they should be browser-reachable. Allowed package files must still be reachable through `fileMap`.
+Values for `allowPackages` are exact package names. Dependencies and installed optional dependencies of packages in `allowPackages` are also allowed automatically. Peer dependencies must be listed explicitly if they should be browser-reachable. Allowed package files must still be reachable through `mounts`.
 
-## File Map
+## Mounts
 
-Use `fileMap` to map public URLs to file paths on disk. `basePath` defines the shared public mount point, and the `fileMap` keys are URL patterns relative to that base path. The values are root-relative file path patterns.
+By default, the asset server mounts the `app` directory at `/app` and `node_modules` at `/npm`. Use `mounts` to replace these defaults. Keys are public paths relative to `basePath`, and values are directory paths relative to `rootDir`.
 
 ```ts
 import { createAssetServer } from 'remix/assets'
 
 let assetServer = createAssetServer({
   basePath: '/assets',
-  fileMap: {
-    '/app/*path': 'app/*path',
-    '/npm/*path': 'node_modules/*path',
+  mounts: {
+    source: 'app',
+    vendor: 'node_modules',
   },
   allowFiles: ['app/routes.ts', 'app/**/public/**'],
   allowPackages: ['remix'],
 })
 ```
 
-`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. For example, with `basePath: '/assets'`, a `fileMap` key of `'/app/*path'` is served at `/assets/app/*path`.
+Package managers that install outside `rootDir`, such as pnpm's global virtual store, are handled without configuration: the asset server reads the store location from the nearest `node_modules/.modules.yaml` and mounts it internally so those package files still resolve to public URLs. A store that a configured mount already covers, such as pnpm's default `node_modules/.pnpm`, is left alone.
 
 ### File watching
 
@@ -123,10 +175,6 @@ import { createAssetServer } from 'remix/assets'
 
 let assetServer = createAssetServer({
   basePath: '/assets',
-  fileMap: {
-    '/app/*path': 'app/*path',
-    '/npm/*path': 'node_modules/*path',
-  },
   allowFiles: ['app/routes.ts', 'app/**/public/**'],
   allowPackages: ['remix'],
 })
@@ -145,10 +193,6 @@ import { createAssetServer } from 'remix/assets'
 
 let assetServer = createAssetServer({
   basePath: '/assets',
-  fileMap: {
-    '/app/*path': 'app/*path',
-    '/npm/*path': 'node_modules/*path',
-  },
   allowFiles: ['app/routes.ts', 'app/**/public/**'],
   allowPackages: ['remix'],
   watch: false,
@@ -162,10 +206,6 @@ import { createAssetServer } from 'remix/assets'
 
 let assetServer = createAssetServer({
   basePath: '/assets',
-  fileMap: {
-    '/app/*path': 'app/*path',
-    '/npm/*path': 'node_modules/*path',
-  },
   allowFiles: ['app/routes.ts', 'app/**/public/**'],
   allowPackages: ['remix'],
   watch: {
@@ -174,13 +214,82 @@ let assetServer = createAssetServer({
 })
 ```
 
+## Script Entries
+
+Use `assetServer.getScriptEntry()` to get everything needed to load a script and its dependencies.
+
+```ts
+let { href, importMap, preloads } = await assetServer.getScriptEntry('app/assets/entry.tsx')
+```
+
+This can be used when rendering a document shell:
+
+```tsx
+import type { Handle, RemixNode } from 'remix/ui'
+import { ImportMap } from 'remix/ui/server'
+import { assetServer } from './assets.ts'
+
+let { href, importMap, preloads } = await assetServer.getScriptEntry('app/assets/entry.tsx')
+
+export function Document(handle: Handle<{ children: RemixNode }>) {
+  return () => (
+    <html>
+      <head>
+        {/* ... */}
+        <ImportMap value={importMap} />
+        {preloads.map((preload) => (
+          <link rel="modulepreload" href={preload} />
+        ))}
+        <script type="module" src={href} />
+      </head>
+      <body>{handle.props.children}</body>
+    </html>
+  )
+}
+```
+
+This can also be used for resolved client entries in [`remix/ui`](https://github.com/remix-run/remix/tree/main/packages/ui) when using `import.meta.url` as the client entry ID:
+
+```tsx
+import { renderToStream } from 'remix/ui/server'
+import { assetServer } from './assets.ts'
+
+let stream = renderToStream(<App />, {
+  async resolveClientEntry(entryId, component) {
+    let { href, importMap, preloads } = await assetServer.getScriptEntry(entryId)
+
+    return {
+      href,
+      importMap,
+      preloads,
+      exportName: entryId.split('#')[1] || component.name,
+    }
+  },
+  // ...
+})
+```
+
 ## 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/actions/public/entry.ts')
-// '/assets/app/actions/public/entry.ts'
+let src = await assetServer.getHref('app/media/public/logo.svg')
+// '/assets/app/media/public/logo.svg'
+```
+
+## Inspection
+
+Use `getAssets()` for a sorted list of files that are currently browser-reachable through the
+asset server. Use `getAssetDetails()` with a public URL or file path to inspect its mapping, file
+type, access rules, and reachability status.
+
+```ts
+let assets = await assetServer.getAssets()
+// [{ url: '/assets/app/actions/public/entry.ts', filePath: '/project/app/actions/public/entry.ts', ... }]
+
+let details = await assetServer.getAssetDetails('/assets/app/actions/public/entry.ts')
+// { status: 'reachable', type: 'script', ... }
 ```
 
 For configured `files` assets, you can also pass a `transform` pipeline to build a request URL with custom file transforms. Basic transforms are written as strings, while dynamic transforms use `[name, param]` tuples.
@@ -192,6 +301,16 @@ let src = await assetServer.getHref('app/media/public/image.png', {
 // '/assets/app/media/public/image.png?transform=resize%3A100x100&transform=webp'
 ```
 
+## Import Maps
+
+Scripts retain their imports as authored and rely on import maps for resolution in the browser. `assetServer.getScriptEntry()` returns the import map for a single rendered script entry. Use `assetServer.getImportMap()` directly when you need to generate a combined import map for multiple script roots or other custom graph-level behavior.
+
+```ts
+let importMap = await assetServer.getImportMap(['app/assets/entry.tsx', 'app/assets/search.tsx'])
+```
+
+Without fingerprinting, import maps resolve authored specifiers to stable asset URLs. With fingerprinting enabled, the same import maps resolve stable asset URLs to content-fingerprinted asset URLs.
+
 ## 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.
@@ -214,29 +333,23 @@ let preloads = await assetServer.getPreloads([
 
 By default, assets are served at stable URLs with ETags and `Cache-Control: no-cache`.
 
-If you want clients to cache assets aggressively without revalidation, you can opt into source-based fingerprinting.
+If you want clients to cache assets aggressively without revalidation, you can opt into content-based fingerprinting.
 
 ```ts
 import { createAssetServer } from 'remix/assets'
 
 let assetServer = createAssetServer({
   basePath: '/assets',
-  fileMap: {
-    '/app/*path': 'app/*path',
-    '/npm/*path': 'node_modules/*path',
-  },
   allowFiles: ['app/routes.ts', 'app/**/public/**'],
   allowPackages: ['remix'],
   watch: false,
-  fingerprint: {
-    buildId: process.env.GITHUB_SHA,
-  },
+  fingerprint: true,
 })
 ```
 
 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`.
+Fingerprints are based on emitted asset contents. This allows unchanged assets to keep the same URL across deployments, but it assumes that files on disk won't change after a URL is generated, so fingerprinting requires `watch: false`.
 
 ## Target
 
@@ -247,10 +360,6 @@ import { createAssetServer } from 'remix/assets'
 
 let assetServer = createAssetServer({
   basePath: '/assets',
-  fileMap: {
-    '/app/*path': 'app/*path',
-    '/npm/*path': 'node_modules/*path',
-  },
   allowFiles: ['app/routes.ts', 'app/**/public/**'],
   allowPackages: ['remix'],
   target: {
@@ -272,10 +381,6 @@ import { createAssetServer } from 'remix/assets'
 
 let assetServer = createAssetServer({
   basePath: '/assets',
-  fileMap: {
-    '/app/*path': 'app/*path',
-    '/npm/*path': 'node_modules/*path',
-  },
   allowFiles: ['app/routes.ts', 'app/**/public/**'],
   allowPackages: ['remix'],
   sourceMaps: 'external',
@@ -289,10 +394,6 @@ import { createAssetServer } from 'remix/assets'
 
 let assetServer = createAssetServer({
   basePath: '/assets',
-  fileMap: {
-    '/app/*path': 'app/*path',
-    '/npm/*path': 'node_modules/*path',
-  },
   allowFiles: ['app/routes.ts', 'app/**/public/**'],
   allowPackages: ['remix'],
   sourceMaps: 'inline',
@@ -309,10 +410,6 @@ import { createAssetServer } from 'remix/assets'
 
 let assetServer = createAssetServer({
   basePath: '/assets',
-  fileMap: {
-    '/app/*path': 'app/*path',
-    '/npm/*path': 'node_modules/*path',
-  },
   allowFiles: ['app/routes.ts', 'app/**/public/**'],
   allowPackages: ['remix'],
   minify: true,
@@ -330,10 +427,6 @@ import { createAssetServer } from 'remix/assets'
 
 let assetServer = createAssetServer({
   basePath: '/assets',
-  fileMap: {
-    '/app/*path': 'app/*path',
-    '/npm/*path': 'node_modules/*path',
-  },
   allowFiles: ['app/routes.ts', 'app/**/public/**'],
   allowPackages: ['remix'],
   scripts: {
@@ -355,10 +448,6 @@ import { createAssetServer } from 'remix/assets'
 
 let assetServer = createAssetServer({
   basePath: '/assets',
-  fileMap: {
-    '/app/*path': 'app/*path',
-    '/npm/*path': 'node_modules/*path',
-  },
   allowFiles: ['app/routes.ts', 'app/**/public/**'],
   allowPackages: ['remix'],
   scripts: {
@@ -376,7 +465,6 @@ import { createAssetServer } from 'remix/assets'
 
 let assetServer = createAssetServer({
   basePath: '/assets',
-  fileMap: { '/app/*path': 'app/*path' },
   allowFiles: ['app/routes.ts', 'app/**/public/**'],
   denyFiles: ['app/**/*.test.*'],
   scripts: {
@@ -404,10 +492,6 @@ import { createAssetServer } from 'remix/assets'
 
 let assetServer = createAssetServer({
   basePath: '/assets',
-  fileMap: {
-    '/app/*path': 'app/*path',
-    '/npm/*path': 'node_modules/*path',
-  },
   allowFiles: ['app/routes.ts', 'app/**/public/**'],
   allowPackages: ['remix'],
   files: {
@@ -430,10 +514,6 @@ import sharp from 'sharp'
 
 let assetServer = createAssetServer({
   basePath: '/assets',
-  fileMap: {
-    '/app/*path': 'app/*path',
-    '/npm/*path': 'node_modules/*path',
-  },
   allowFiles: ['app/routes.ts', 'app/**/public/**'],
   allowPackages: ['remix'],
   files: {
@@ -464,10 +544,6 @@ import { createAssetServer, defineFileTransform } from 'remix/assets'
 
 let assetServer = createAssetServer({
   basePath: '/assets',
-  fileMap: {
-    '/app/*path': 'app/*path',
-    '/npm/*path': 'node_modules/*path',
-  },
   allowFiles: ['app/routes.ts', 'app/**/public/**'],
   allowPackages: ['remix'],
   files: {
@@ -512,10 +588,6 @@ import { optimize as optimizeSvg } from 'svgo'
 
 let assetServer = createAssetServer({
   basePath: '/assets',
-  fileMap: {
-    '/app/*path': 'app/*path',
-    '/npm/*path': 'node_modules/*path',
-  },
   allowFiles: ['app/routes.ts', 'app/**/public/**'],
   allowPackages: ['remix'],
   files: {
@@ -535,11 +607,9 @@ let assetServer = createAssetServer({
 
 #### File transform caching
 
-Use `files.cache` to store transformed file outputs via a [`file-storage`](https://github.com/remix-run/remix/tree/main/packages/file-storage) backend.
+Use `files.cache` to store transformed file outputs via a [`file-storage`](https://github.com/remix-run/remix/tree/main/packages/file-storage) backend. Without `files.cache`, transformed file outputs are recomputed per request.
 
-Without `files.cache`, transformed file outputs are recomputed per request.
-
-If `fingerprint.buildId` is set, the file cache can be reused across server restarts for the same build.
+`files.cacheKey` scopes transformed file cache entries. Use a stable identifier, such as a commit SHA, when you want unchanged transformed files to be reused across server restarts for the same build.
 
 ```ts
 import * as path from 'node:path'
@@ -548,14 +618,11 @@ import { createFsFileStorage } from 'remix/file-storage/fs'
 
 let assetServer = createAssetServer({
   basePath: '/assets',
-  fileMap: {
-    '/app/*path': 'app/*path',
-    '/npm/*path': 'node_modules/*path',
-  },
   allowFiles: ['app/routes.ts', 'app/**/public/**'],
   allowPackages: ['remix'],
   files: {
     cache: createFsFileStorage(path.resolve('.tmp/assets-cache')),
+    cacheKey: process.env.GIT_COMMIT_SHA,
     extensions: ['.svg', '.png', '.jpg', '.jpeg', '.woff2'],
     transforms: {
       /*...*/
@@ -573,10 +640,6 @@ import { createAssetServer } from 'remix/assets'
 
 let assetServer = createAssetServer({
   basePath: '/assets',
-  fileMap: {
-    '/app/*path': 'app/*path',
-    '/npm/*path': 'node_modules/*path',
-  },
   allowFiles: ['app/routes.ts', 'app/**/public/**'],
   allowPackages: ['remix'],
   files: {
@@ -624,10 +687,6 @@ import { createAssetServer } from 'remix/assets'
 
 let assetServer = createAssetServer({
   basePath: '/assets',
-  fileMap: {
-    '/app/*path': 'app/*path',
-    '/npm/*path': 'node_modules/*path',
-  },
   allowFiles: ['app/routes.ts', 'app/**/public/**'],
   allowPackages: ['remix'],
   onError(error) {
@@ -651,9 +710,8 @@ import { createAssetServer } from 'remix/assets'
 let isDevelopment = process.env.NODE_ENV === 'development'
 let assetServer = createAssetServer({
   basePath: '/assets',
-  fileMap: { '/app/*path': 'app/*path' },
   allowFiles: ['app/routes.ts', 'app/**/public/**'],
-  denyFiles: ['app/**/*.test.*'],
+  allowPackages: ['remix'],
   hmr: isDevelopment
     ? async () => (await import('remix/node-hmr/runtime')).createBrowserHmrChannel()
     : undefined,
@@ -661,6 +719,30 @@ let assetServer = createAssetServer({
 })
 ```
 
+Use `moduleImporter` to customize how HMR dynamically imports updated browser modules. It is resolved relative to the asset server's root directory and must point to a browser module exporting:
+
+```ts
+export function importModule(specifier: string, parentUrl: string): Promise<Record<string, unknown>>
+```
+
+HMR appends mappings for updated modules to the document in additional `<script type="importmap">` elements. Use `remix/multiple-import-maps-polyfill` when these updates must work in browsers without native support for multiple import maps:
+
+```ts
+import { createAssetServer } from 'remix/assets'
+import { createBrowserHmrChannel } from 'remix/node-hmr/runtime'
+
+let assetServer = createAssetServer({
+  basePath: '/assets',
+  allowFiles: ['app/routes.ts', 'app/**/public/**'],
+  allowPackages: ['remix'],
+  hmr: {
+    channel: createBrowserHmrChannel,
+    moduleImporter: 'remix/multiple-import-maps-polyfill',
+  },
+  watch: true,
+})
+```
+
 ### `import.meta.hot`
 
 The `import.meta.hot` API provided by `assets` is a small runtime contract for modules that can handle updates without reloading the page. It is primarily intended for browser modules compiled by `assets`, but it can also be used directly.
@@ -798,7 +880,6 @@ if (import.meta.hot) {
 - [`fetch-router`](https://github.com/remix-run/remix/tree/main/packages/fetch-router) - A Fetch-based router that pairs naturally with `assets`
 - [`node-hmr`](https://github.com/remix-run/remix/tree/main/packages/node-hmr) - Provides the server-side `import.meta.hot` runtime and browser HMR channel used by `hmr`
 - [`ui-hmr`](https://github.com/remix-run/remix/tree/main/packages/ui-hmr) - Provides a Remix UI component HMR loader for `scripts.loaders`
-- [`route-pattern`](https://github.com/remix-run/remix/tree/main/packages/route-pattern) - Route-pattern syntax for URL and route file matching
 
 ## License
 

package/src/auth/README.md

@@ -5,7 +5,7 @@ Composable browser authentication primitives for Remix. Use this package to veri
 ## Features
 
 - Small, composable primitives: `verifyCredentials()`, `startExternalAuth()`, `finishExternalAuth()`, `refreshExternalAuth()`, and `completeAuth()`
-- Built-in provider support for Google, Microsoft, Okta, Auth0, GitHub, Facebook, X, and Atmosphere
+- Built-in provider support for Google, Microsoft, Okta, Auth0, GitHub, Facebook, and X
 - Module-scope provider configuration for boot-time validation and stable callback URLs
 - App-owned session records so you decide what auth data to persist
 - Shared session completion for credentials and external auth flows
@@ -276,7 +276,7 @@ router.get(routes.app.dashboard, {
 
 A typical external auth flow looks like this:
 
-1. Create the provider once at module scope. For Atmosphere, call `provider.prepare(handleOrDid)` only when starting the login flow.
+1. Create the provider once at module scope.
 2. Call `startExternalAuth()` from the login route.
 3. Call `finishExternalAuth()` from the callback route.
 4. Persist any provider tokens you want to reuse later.
@@ -286,12 +286,11 @@ A typical external auth flow looks like this:
 
 ## Built-in External Auth Providers
 
-When one of the built-in providers matches your auth provider, start there. Google, Microsoft, Okta, and Auth0 use the shared OIDC runtime. GitHub, Facebook, X, and Atmosphere use built-in custom OAuth flows.
+When one of the built-in providers matches your auth provider, start there. Google, Microsoft, Okta, and Auth0 use the shared OIDC runtime. GitHub, Facebook, and X use built-in custom OAuth flows.
 
 ```ts
 import {
   createAuth0AuthProvider,
-  createAtmosphereAuthProvider,
   createFacebookAuthProvider,
   createGitHubAuthProvider,
   createGoogleAuthProvider,
@@ -307,12 +306,6 @@ let auth0Provider = createAuth0AuthProvider({
   redirectUri: new URL('/auth/auth0/callback', env.APP_ORIGIN),
 })
 
-let atmosphereProvider = createAtmosphereAuthProvider({
-  clientId: new URL('/oauth/client-metadata.json', env.APP_ORIGIN),
-  redirectUri: new URL('/auth/atmosphere/callback', env.APP_ORIGIN),
-  sessionSecret: env.SESSION_SECRET,
-})
-
 let facebookProvider = createFacebookAuthProvider({
   clientId: env.FACEBOOK_CLIENT_ID,
   clientSecret: env.FACEBOOK_CLIENT_SECRET,
@@ -361,11 +354,7 @@ Notes:
 - `createMicrosoftAuthProvider()` adds the `tenant` option and builds the issuer from it
 - `createOktaAuthProvider()` expects the full Okta issuer URL, usually something like `https://example.okta.com/oauth2/default`
 - `createAuth0AuthProvider()` expects your Auth0 domain and derives the issuer URL for you
-- `createAtmosphereAuthProvider()` returns a module-scope provider with `prepare(handleOrDid)` for request-time atproto account discovery before `startExternalAuth()`
-- Atmosphere callback routes pass the module-scope provider directly to `finishExternalAuth()`; the original handle or DID is stored in the sealed OAuth transaction state
-- `createAtmosphereAuthProvider()` requires `sessionSecret` and seals the in-flight account, authorization server, nonce, and DPoP key state into the existing OAuth transaction stored in your app session, so you do not need a separate file or database store for the redirect step
-- `createAtmosphereAuthProvider()` returns DPoP-bound token material in `result.tokens`, including `accessToken`, `refreshToken`, authorization server refresh details, and `dpop` JWK state for follow-up DPoP-signed requests
-- `refreshExternalAuth()` supports built-in OIDC providers, X, and Atmosphere when the stored token bundle includes a refresh token
+- `refreshExternalAuth()` supports built-in OIDC providers and X when the stored token bundle includes a refresh token
 - Providers only return refresh tokens when configured to request offline access, such as `authorizationParams: { access_type: 'offline' }` for Google or adding `offline.access` to X scopes
 - Use `mapProfile()` with `createOIDCAuthProvider()` when you want `result.profile` to have an app-specific type before it reaches your route code
 
@@ -425,6 +414,53 @@ router.get('/auth/company/callback', async (context) => {
 })
 ```
 
+Provider packages for other OAuth protocols can use `createOAuthProvider()` to implement the authorization, callback, and optional refresh hooks consumed by `startExternalAuth()`, `finishExternalAuth()`, and `refreshExternalAuth()`.
+
+```ts
+import { createOAuthProvider } from 'remix/auth'
+import type { OAuthTokens } from 'remix/auth'
+
+interface AcmeProfile {
+  id: string
+  email: string
+}
+
+interface AcmeTokens extends OAuthTokens {
+  resourceServer: string
+}
+
+export function createAcmeAuthProvider(options: AcmeAuthProviderOptions) {
+  return createOAuthProvider<AcmeProfile, 'acme', AcmeTokens>('acme', {
+    async createAuthorizationURL(transaction) {
+      let metadata = await discoverAuthorizationServer(options)
+
+      transaction.providerState = await encryptProviderState(metadata)
+      return createAuthorizationRequest(metadata, transaction)
+    },
+    async handleCallback(context, transaction) {
+      let metadata = await decryptProviderState(transaction.providerState)
+      let tokens = await exchangeAuthorizationCode(metadata, context, transaction)
+      let profile = await loadProfile(tokens)
+
+      return {
+        provider: 'acme',
+        account: {
+          provider: 'acme',
+          providerAccountId: profile.id,
+        },
+        profile,
+        tokens,
+      }
+    },
+    async refreshTokens(tokens) {
+      return refreshAcmeTokens(tokens)
+    },
+  })
+}
+```
+
+The runtime may write a serialized value to `transaction.providerState` during `createAuthorizationURL()`. Remix persists that value with the OAuth transaction and returns it to `handleCallback()`. Treat it as provider-owned opaque data, and encrypt sensitive values because session storage is not guaranteed to be confidential. Extending `OAuthTokens` preserves provider-specific fields through callback and refresh results without requiring those fields to become part of Remix's built-in token model.
+
 ## Related Packages
 
 - [`auth-middleware`](https://github.com/remix-run/remix/tree/main/packages/auth-middleware) - Request authentication and route protection helpers