@oxy.so/app-preset 3.5.0 → 3.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/NOTICE CHANGED
@@ -16,6 +16,8 @@ everyone, including paying commercial licensees, and cannot be waived.
16
16
  THIRD PARTY COMPONENTS
17
17
  ----------------------------------------------------------------------------
18
18
 
19
- This package contains no third party source. Its dependencies are resolved
20
- and installed by the package manager and remain governed by their own
21
- licenses.
19
+ metro/static-hydration/renderer.js adapts the static renderer from
20
+ @expo/router-server 58.0.14–58.0.16, Copyright © 2026 650 Industries, under
21
+ the MIT license included at metro/static-hydration/EXPO-LICENSE.
22
+ Other dependencies are resolved and installed by the package manager and
23
+ remain governed by their own licenses.
package/README.md CHANGED
@@ -24,6 +24,51 @@ and JSON.
24
24
  | CSS base | `@oxy.so/app-preset/base.css` | Tailwind v4 + NativeWind + Bloom design-token imports + SDK `@source` globs |
25
25
  | tsconfig | `@oxy.so/app-preset/tsconfig/{base,frontend,backend}.json` | the shared strict/composite TypeScript bases |
26
26
 
27
+ ## Static web hydration on Expo 58
28
+
29
+ Apps exporting static HTML can enable the reviewed Expo 58 compatibility adapter:
30
+
31
+ ```js
32
+ module.exports = createOxyMetroConfig(__dirname, {
33
+ staticHydrationBoundary: true,
34
+ });
35
+ ```
36
+
37
+ Expo Router's renderer in `@expo/router-server` 58.0.14–58.0.16 renders the app
38
+ inside `+html`, but the browser hydrates only `#root`. Document siblings then
39
+ change React `useId` paths. An ID in text (for example Bloom's scoped stylesheet)
40
+ causes React to replace the workspace during hydration.
41
+
42
+ The adapter renders the app at its own React root and then renders the document
43
+ around that completed markup. It preserves Expo's route/loader contexts,
44
+ metadata, asset order, bootstrap script, fonts and styles, including resources
45
+ registered inside async Suspense content. React’s public `prerender` API waits
46
+ for all content without hidden streaming segments that would require JavaScript. React 19's hoisted document resources
47
+ move into the final head; the app's remaining HTML and hydration markers retain
48
+ the exact bytes produced by React. Server errors fail the static export. `Head` metadata is collected from the
49
+ routed app tree; `+html` owns its literal head and `useServerDocumentContext`,
50
+ as in Expo (the route-aware `Head` component requires navigation context).
51
+
52
+ Only web/node bundles and `output: 'static'` use the adapter. Live streaming
53
+ requests delegate to Expo unchanged. It is off by default; enabling it with an
54
+ unreviewed router-server version fails with a diagnostic instead of silently
55
+ assuming private APIs are compatible. Optional peer ranges do not restrict
56
+ older Expo apps when the adapter is off. Review/remove the adapter when Expo
57
+ fixes the app/document render boundary upstream. The adapted Expo code retains
58
+ its MIT license in `metro/static-hydration/EXPO-LICENSE`.
59
+
60
+ Development uses the same boundary when starting Expo with
61
+ `EXPO_WEB_DEV_HYDRATE=1`. Expo otherwise calls `createRoot`, replacing its server
62
+ markup rather than hydrating it. In development the adapter also uses Expo's
63
+ actual web `withDevTools` wrapper: its refresh indicator is initially invisible,
64
+ but its sibling still changes React's `useId` paths. Production does not include
65
+ that wrapper. Keep Fast Refresh enabled; do not compensate for IDs in app code.
66
+
67
+ Verify production exports, not just Metro development: JavaScript-disabled
68
+ screenshots must show real chrome, and hydration must retain the same workspace
69
+ DOM node without recoverable React errors. The package tests exercise real
70
+ `prerender` and `hydrateRoot`; publication runs those gates too.
71
+
27
72
  ## Usage
28
73
 
29
74
  ### 1. Config plugin (`app.config.js` / `app.json`)
package/metro/index.js CHANGED
@@ -37,6 +37,8 @@
37
37
  * module ids, its resolver shims, inline requires), so a worker runtime can
38
38
  * load the app's bundle. Pair it with the Babel factory's option of the same
39
39
  * name; neither works alone. Needs `react-native-worklets` installed.
40
+ * @param {boolean} [options.staticHydrationBoundary=false] Correct the app/document
41
+ * render boundary in Expo 58 static exports; guarded to reviewed router versions.
40
42
  * @returns {import('metro-config').MetroConfig}
41
43
  */
42
44
  const { getDefaultConfig } = require('expo/metro-config');
@@ -45,6 +47,7 @@ const fs = require('node:fs');
45
47
  const path = require('node:path');
46
48
  const { resolveOxyBuildId } = require('../build-id');
47
49
  const { requireFromProject } = require('../plugin/requireFromProject');
50
+ const { withStaticHydrationBoundary } = require('./static-hydration/resolver');
48
51
 
49
52
  function escapeRegExp(value) {
50
53
  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
@@ -312,9 +315,10 @@ function withWorkletsBundleMode(config, projectRoot) {
312
315
  }
313
316
 
314
317
  function createOxyMetroConfigWithBloom(projectRoot, options = {}) {
315
- const { workletsBundleMode = false } = options;
318
+ const { workletsBundleMode = false, staticHydrationBoundary = false } = options;
316
319
  const nativeWindConfig = createOxyMetroConfig(projectRoot, options);
317
- const config = withBloomSingleInstance(nativeWindConfig, projectRoot);
320
+ let config = withBloomSingleInstance(nativeWindConfig, projectRoot);
321
+ if (staticHydrationBoundary) config = withStaticHydrationBoundary(config, projectRoot);
318
322
  return workletsBundleMode ? withWorkletsBundleMode(config, projectRoot) : config;
319
323
  }
320
324
 
@@ -0,0 +1,21 @@
1
+ The MIT License (MIT)
2
+
3
+ Copyright (c) 2015-present 650 Industries, Inc. (aka Expo)
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,38 @@
1
+ const { parseFragment } = require('parse5');
2
+
3
+ /**
4
+ * React hoists resources outside the root container. Read those exact segments
5
+ * instead of guessing from tag names: a link with a handler belongs to the app,
6
+ * while an otherwise identical link without a handler may belong to the head.
7
+ */
8
+ function extractDocumentResources(html) {
9
+ const fragment = parseFragment(html, { sourceCodeLocationInfo: true });
10
+ const root = fragment.childNodes.find(
11
+ (node) =>
12
+ node.tagName === 'div' &&
13
+ node.attrs.some(({ name, value }) => name === 'id' && value === 'root'),
14
+ );
15
+ for (const node of fragment.childNodes) {
16
+ if (node === root || node.nodeName === '#comment') continue;
17
+ if (node.nodeName === '#text' && !node.value.trim()) continue;
18
+ const attrs = new Map((node.attrs ?? []).map(({ name, value }) => [name, value]));
19
+ const resource =
20
+ ['title', 'meta', 'base', 'link', 'style'].includes(node.tagName) ||
21
+ (node.tagName === 'script' && attrs.has('async') && attrs.has('src'));
22
+ if (!resource) {
23
+ throw new Error(
24
+ 'Static rendering emitted content outside #root instead of a completed document resource.',
25
+ );
26
+ }
27
+ }
28
+ const location = root?.sourceCodeLocation;
29
+ if (!location?.startTag || !location.endTag) {
30
+ throw new Error('The static app renderer did not produce its #root container.');
31
+ }
32
+ return {
33
+ appHtml: html.slice(location.startTag.endOffset, location.endTag.startOffset),
34
+ resources: html.slice(0, location.startOffset) + html.slice(location.endOffset),
35
+ };
36
+ }
37
+
38
+ module.exports = { extractDocumentResources };
@@ -0,0 +1,39 @@
1
+ const { createElement } = require('react');
2
+ const { prerender } = require('react-dom/static');
3
+ const { extractDocumentResources } = require('./document-resources');
4
+
5
+ async function renderToHtml(element, options = {}) {
6
+ const errors = [];
7
+ const { prelude, postponed } = await prerender(element, {
8
+ // Even completed boundaries can otherwise be outlined into hidden segments
9
+ // once they exceed React's default progressive chunk size.
10
+ progressiveChunkSize: Number.MAX_SAFE_INTEGER,
11
+ ...options,
12
+ onError(error) {
13
+ errors.push(error);
14
+ },
15
+ });
16
+ if (errors.length) throw errors[0];
17
+ if (postponed) throw new Error('The static app render did not complete.');
18
+ return new Response(prelude).text();
19
+ }
20
+
21
+ /**
22
+ * The browser hydrates #root, not +html. Give the app its own React render root
23
+ * on the server as well: document siblings must not enter its useId tree path.
24
+ * Only markup produced by React is passed to createDocument, never user HTML.
25
+ */
26
+ async function renderHydratableDocument(app, createDocument, options = {}) {
27
+ // A single-child host container adds no useId fork; it separates resources
28
+ // hoisted by React from ordinary app nodes, including root-level links.
29
+ const rendered = await renderToHtml(createElement('div', { id: 'root' }, app), {
30
+ signal: options.signal,
31
+ });
32
+ const { appHtml, resources } = extractDocumentResources(rendered);
33
+ // Static prerender with the unlimited progressive chunk size waits for
34
+ // Suspense without hidden segments. Its styles and fonts now exist too.
35
+ const documentHtml = await renderToHtml(createDocument(appHtml), options);
36
+ return documentHtml.replace('</head>', () => `${resources}</head>`);
37
+ }
38
+
39
+ module.exports = { renderHydratableDocument };
@@ -0,0 +1,106 @@
1
+ /*
2
+ * Adapted from @expo/router-server 58.0.14 / 58.0.16 renderStreamingContent.
3
+ * Copyright © 2026 650 Industries. MIT license: ./EXPO-LICENSE.
4
+ * Static output only. Keep Expo's live streaming renderer unchanged.
5
+ */
6
+ const React = require('react');
7
+ const fonts = require('expo-font/build/server');
8
+ const { ExpoRoot } = require('expo-router');
9
+ const { ctx } = require('expo-router/_ctx');
10
+ const Head = require('expo-router/head').default;
11
+ const { ServerDocument } = require('expo-router/internal/server');
12
+ const {
13
+ InnerRoot,
14
+ getRouteInfoForLocation,
15
+ registerStaticRootComponent,
16
+ } = require('expo-router/internal/static');
17
+ const { normalizeCssAssets } = require('expo-server/private');
18
+ const { getRootComponent } = require('@expo/router-server/build/static/getRootComponent');
19
+ const assets = require('@expo/router-server/build/utils/react');
20
+ const { serializeHelmetToHtml } = require('@expo/router-server/build/utils/html');
21
+ const original = require('@expo/router-server/build/server/renderStreamingContent');
22
+ const { renderHydratableDocument } = require('./render-document');
23
+
24
+ const h = React.createElement;
25
+
26
+ function StaticApp({ headContext, loadedData, element }) {
27
+ return h(Head.Provider, { context: headContext }, h(InnerRoot, { loadedData }, element));
28
+ }
29
+
30
+ // Expo's web entry wraps the entire qualified app in development. Its sibling
31
+ // DevLoadingView participates in React's useId tree even while it renders null.
32
+ // Use the real wrapper on the server too, rather than compensating for its IDs.
33
+ const StaticAppRoot =
34
+ process.env.NODE_ENV !== 'production'
35
+ ? require('expo/build/launch/withDevTools.web').withDevTools(StaticApp)
36
+ : StaticApp;
37
+
38
+ function getStreamingContent(location, options) {
39
+ if (options?.output !== 'static') return original.getStreamingContent(location, options);
40
+ return fonts.withServerContext(async () => {
41
+ const headContext = {};
42
+ const Document = getRootComponent();
43
+ const route = getRouteInfoForLocation(ctx, location);
44
+ // No document wrapper here: this is exactly the boundary hydrated in #root.
45
+ const { element, getStyleElement } = registerStaticRootComponent(ExpoRoot, {
46
+ location,
47
+ context: ctx,
48
+ });
49
+ // Match Expo's per-page reset; React Navigation caches named contexts globally.
50
+ globalThis.__react_navigation__elements_contexts = new Map();
51
+ const loaderKey = options.loader ? options.loader.key + location.search : null;
52
+ const loadedData = loaderKey ? { [loaderKey]: options.loader.data ?? null } : null;
53
+ const app = h(StaticAppRoot, { headContext, loadedData, element });
54
+
55
+ const html = await renderHydratableDocument(
56
+ app,
57
+ (appHtml) => {
58
+ const css = assets.createInjectedCssAsNodes(normalizeCssAssets(options.assets));
59
+ const scripts = assets.createInjectedScriptAsNodes(options.assets?.js ?? []);
60
+ const data = {
61
+ headNodes: [
62
+ ...(options.metadata?.headNodes ?? []),
63
+ options.assets?.favicon ? assets.createFaviconAsNode(options.assets.favicon) : null,
64
+ getStyleElement({ key: 'rnw-style-element' }),
65
+ ...(css.headNodes ?? []),
66
+ ...(scripts.headNodes ?? []),
67
+ ...assets.createInjectedFontsAsNodes(fonts.getServerResourceDescriptors()),
68
+ ].filter(Boolean),
69
+ bodyNodes: scripts.bodyNodes,
70
+ };
71
+ return h(
72
+ ServerDocument,
73
+ { data },
74
+ h(
75
+ Document,
76
+ route,
77
+ h('div', { id: 'root', dangerouslySetInnerHTML: { __html: appHtml } }),
78
+ ),
79
+ );
80
+ },
81
+ {
82
+ progressiveChunkSize: Number.MAX_SAFE_INTEGER,
83
+ bootstrapScriptContent:
84
+ assets.getBootstrapContents({
85
+ hydrate: options.hydrate ?? true,
86
+ loadedData,
87
+ }) || undefined,
88
+ signal: options.request?.signal,
89
+ },
90
+ );
91
+ // Preserve Expo's legacy Head API alongside the metadata nodes above.
92
+ const routeHead = headContext.helmet;
93
+ // Helmet initializes an empty title even if no route set one. It must not
94
+ // override the document's own title in apps using only generateMetadata.
95
+ const hasTitle = routeHead?.title?.toComponent().some((node) => node.props.children !== '');
96
+ const helmet = serializeHelmetToHtml(
97
+ routeHead ? { ...routeHead, title: hasTitle ? routeHead.title : undefined } : undefined,
98
+ );
99
+ return html
100
+ .replace('<head>', () => `<head>${helmet.headTags}`)
101
+ .replace('<html ', () => `<html ${helmet.htmlAttributes} `)
102
+ .replace('<body', () => `<body${helmet.bodyAttributes ? ` ${helmet.bodyAttributes}` : ''}`);
103
+ });
104
+ }
105
+
106
+ module.exports = { getStreamingContent, resolveMetadata: original.resolveMetadata };
@@ -0,0 +1,32 @@
1
+ const path = require('node:path');
2
+ const { requireFromProject } = require('../../plugin/requireFromProject');
3
+
4
+ /** Opt-in compatibility adapter for Expo's static document/app render boundary. */
5
+ function withStaticHydrationBoundary(config, projectRoot) {
6
+ const { version } = requireFromProject('@expo/router-server/package.json', projectRoot);
7
+ if (!/^58\.0\.(14|15|16)$/.test(version)) {
8
+ throw new Error(
9
+ `[@oxy.so/app-preset] staticHydrationBoundary supports @expo/router-server 58.0.14–58.0.16; found ${version}. Review the upstream renderer before extending this range.`,
10
+ );
11
+ }
12
+ const adapter = path.join(__dirname, 'renderer.js');
13
+ const parent = config.resolver.resolveRequest;
14
+ config.resolver.resolveRequest = (context, moduleName, platform) => {
15
+ const resolved = parent(context, moduleName, platform);
16
+ if (
17
+ platform === 'web' &&
18
+ context.customResolverOptions?.environment === 'node' &&
19
+ context.originModulePath !== adapter &&
20
+ resolved.type === 'sourceFile' &&
21
+ /[/\\]@expo[/\\]router-server[/\\]build[/\\]server[/\\]renderStreamingContent\.js$/.test(
22
+ resolved.filePath,
23
+ )
24
+ ) {
25
+ return { type: 'sourceFile', filePath: adapter };
26
+ }
27
+ return resolved;
28
+ };
29
+ return config;
30
+ }
31
+
32
+ module.exports = { withStaticHydrationBoundary };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@oxy.so/app-preset",
3
- "version": "3.5.0",
3
+ "version": "3.6.1",
4
4
  "description": "The Oxy distro of Expo — centralized Expo config plugin, Metro/Babel/ESLint factories, Tailwind base CSS and TypeScript bases shared by every Oxy app (Mention, Homiio, Allo, accounts, …). A zero-build package: apps replace copy-pasted config with a single dependency bump.",
5
5
  "main": "./app.plugin.js",
6
6
  "publishConfig": {
@@ -60,7 +60,7 @@
60
60
  "node": ">=18.0.0"
61
61
  },
62
62
  "scripts": {
63
- "prepublishOnly": "node ../../scripts/assert-bun-publish.mjs",
63
+ "prepublishOnly": "node ../../scripts/assert-bun-publish.mjs && bun run test",
64
64
  "test": "node --test __tests__/*.test.js"
65
65
  },
66
66
  "//peerDependencies": "THE TWO @oxy.so PEERS ARE DELIBERATE. This package couples to them by FILE PATH, not by API: `css/base.css` imports `@oxy.so/bloom/design-tokens/theme.css`, and `plugin/withOxyAppPreset.js` requires `@oxy.so/services/plugins/withOxySharedPermissions` (services 11+, where it first exists, so the services floor is the major that ships it). Both peers retain a measured floor and are deliberately OPEN-ENDED above it: Oxy apps always run the latest Bloom and Services, so a new release of either must never need a preset release first. A release that breaks this package's file-path coupling is caught by its own tests and the apps' CI, not by a cap. Never replace either constraint with `*`.",
@@ -77,12 +77,23 @@
77
77
  "react-native-webgpu": ">=0.5.18 <1.0.0",
78
78
  "react-native-worklets": "*",
79
79
  "sharp": ">=0.33.0",
80
- "tailwindcss": ">=4.0.0"
80
+ "tailwindcss": ">=4.0.0",
81
+ "@expo/router-server": "<59.0.0",
82
+ "expo-router": "<59.0.0",
83
+ "expo-font": "<59.0.0",
84
+ "expo-server": "<59.0.0",
85
+ "react": ">=19.0.0 <20.0.0",
86
+ "react-dom": ">=19.0.0 <20.0.0"
81
87
  },
82
88
  "devDependencies": {
83
89
  "expo": "~58.0.14",
84
90
  "nativewind": "5.0.0-preview.3",
85
- "tailwindcss": "4.3.3"
91
+ "tailwindcss": "4.3.3",
92
+ "react": "19.3.0",
93
+ "react-dom": "19.3.0",
94
+ "jsdom": "^29.1.1",
95
+ "expo-router": "~58.0.23",
96
+ "@expo/router-server": "58.0.14"
86
97
  },
87
98
  "peerDependenciesMeta": {
88
99
  "@oxy.so/bloom": {
@@ -111,6 +122,27 @@
111
122
  },
112
123
  "sharp": {
113
124
  "optional": true
125
+ },
126
+ "@expo/router-server": {
127
+ "optional": true
128
+ },
129
+ "expo-router": {
130
+ "optional": true
131
+ },
132
+ "expo-font": {
133
+ "optional": true
134
+ },
135
+ "expo-server": {
136
+ "optional": true
137
+ },
138
+ "react": {
139
+ "optional": true
140
+ },
141
+ "react-dom": {
142
+ "optional": true
114
143
  }
144
+ },
145
+ "dependencies": {
146
+ "parse5": "7.3.0"
115
147
  }
116
148
  }