Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docsite: read the docs-prompt origins from build configuration (#9397)

Cindy Zhanga64fd1ea8517
diff --git a/.github/scripts/ci-docsite-browser.test.mjs b/.github/scripts/ci-docsite-browser.test.mjs
index 8f2fe75b84..c9912cff43 100644
--- a/.github/scripts/ci-docsite-browser.test.mjs
+++ b/.github/scripts/ci-docsite-browser.test.mjs
@@ -80,6 +80,21 @@ describe('docsite-test', () => {
);
});
+ it('builds and tests the docs prompt with placeholder origins only', () => {
+ // One job-level value reaches the build and the browser contracts alike.
+ expect(owner.env).toEqual({
+ NEXT_PUBLIC_INTERNAL_DOCS_ORIGIN: 'https://docs.example.test',
+ NEXT_PUBLIC_DOCS_ACCESS_CHECK_ORIGIN: 'https://probe.example.test',
+ });
+ for (const s of owner.steps) {
+ expect(s.env?.NEXT_PUBLIC_INTERNAL_DOCS_ORIGIN, s.name).toBeUndefined();
+ expect(
+ s.env?.NEXT_PUBLIC_DOCS_ACCESS_CHECK_ORIGIN,
+ s.name,
+ ).toBeUndefined();
+ }
+ });
+
it.each([0, 1])(
'the start step records exit %i from the data tests under bash -e',
async code => {
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index b89a74e261..941242d496 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -544,6 +544,12 @@ jobs:
permissions:
contents: read
pull-requests: read
+ # Placeholder docs-prompt origins: the build and its browser contracts
+ # exercise the configured prompt. Deployed values live only in the
+ # deployment environment, never in this repository.
+ env:
+ NEXT_PUBLIC_INTERNAL_DOCS_ORIGIN: https://docs.example.test
+ NEXT_PUBLIC_DOCS_ACCESS_CHECK_ORIGIN: https://probe.example.test
steps:
- name: Require a branch in this repository or the ci:run label
if: ${{ github.event_name == 'pull_request' && !(github.event.pull_request.head.repo.full_name == github.repository || contains(github.event.pull_request.labels.*.name, 'ci:run')) }}
diff --git a/apps/docsite/e2e/internal-docs-prompt.spec.ts b/apps/docsite/e2e/internal-docs-prompt.spec.ts
index 48c24010bd..3692909b5c 100644
--- a/apps/docsite/e2e/internal-docs-prompt.spec.ts
+++ b/apps/docsite/e2e/internal-docs-prompt.spec.ts
@@ -1,7 +1,8 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
- * @input A production docsite build and exact-origin reachability fixtures
+ * @input A production docsite build configured with the docs and probe origins,
+ * and exact-origin reachability fixtures
* @output Browser evidence of unified banner CTAs and page-view-only dismissal
* @position Docsite integration tests; run against both latest and canary builds
*/
@@ -19,11 +20,26 @@ const deployments = [
];
const isCanary = process.env.DOCSITE_TEST_TARGET !== 'latest';
const target = isCanary ? 'canary' : 'latest';
-const internalOrigin = 'https://astryx.internalmeta.com';
-const probeOrigin = 'https://codebunny.internalmeta.com';
+// The build under test must be configured with these origins (CI builds with
+// placeholder values); the probe and the destination are both routed below.
+const internalOrigin = process.env.NEXT_PUBLIC_INTERNAL_DOCS_ORIGIN ?? '';
+const probeOrigin = process.env.NEXT_PUBLIC_DOCS_ACCESS_CHECK_ORIGIN ?? '';
+const isConfigured = internalOrigin !== '' && probeOrigin !== '';
const noticeName = 'Documentation notice';
const dismissName = 'Dismiss documentation notice for this page view';
+// CI must always run these contracts; a local build without the origins
+// disables the prompt, so there is nothing to check.
+if (!isConfigured && (process.env.CI ?? '') !== '') {
+ throw new Error(
+ 'Set NEXT_PUBLIC_INTERNAL_DOCS_ORIGIN and NEXT_PUBLIC_DOCS_ACCESS_CHECK_ORIGIN for both the docsite build and this run',
+ );
+}
+test.skip(
+ !isConfigured,
+ 'Build and run with NEXT_PUBLIC_INTERNAL_DOCS_ORIGIN and NEXT_PUBLIC_DOCS_ACCESS_CHECK_ORIGIN set',
+);
+
test.afterEach(async ({page}) => {
await page.waitForLoadState('networkidle');
});
diff --git a/apps/docsite/playwright.config.ts b/apps/docsite/playwright.config.ts
index b458d9524b..b60800f82f 100644
--- a/apps/docsite/playwright.config.ts
+++ b/apps/docsite/playwright.config.ts
@@ -22,6 +22,10 @@
* Outside CI an already-running `next start` on the port is reused, so a
* server started by hand works too.
*
+ * The docs-prompt spec needs NEXT_PUBLIC_INTERNAL_DOCS_ORIGIN and
+ * NEXT_PUBLIC_DOCS_ACCESS_CHECK_ORIGIN set for both the build and the run (CI
+ * uses placeholder origins); without them it skips locally and fails in CI.
+ *
* SYNC: When the docsite gains another browser-only contract, add its spec
* under e2e/.
*/
diff --git a/apps/docsite/src/__tests__/internal-docs-prompt.test.tsx b/apps/docsite/src/__tests__/internal-docs-prompt.test.tsx
index a6f8f2c72d..4c0f47f4bc 100644
--- a/apps/docsite/src/__tests__/internal-docs-prompt.test.tsx
+++ b/apps/docsite/src/__tests__/internal-docs-prompt.test.tsx
@@ -42,14 +42,16 @@ declare const jsdom: {reconfigure(options: {url: string}): void};
let Prompt: typeof InternalDocsPrompt;
let href: typeof internalDocsHref;
-const internalOrigin = 'https://astryx.internalmeta.com';
-const probeOrigin = 'https://codebunny.internalmeta.com';
+const internalOrigin = 'https://docs.example.test';
+const probeOrigin = 'https://probe.example.test';
const message = {type: 'codebunny:access-check:v1', reachable: true};
beforeEach(async () => {
vi.resetModules();
vi.useFakeTimers();
vi.stubEnv('NEXT_PUBLIC_DOCS_TARGET', 'latest');
+ vi.stubEnv('NEXT_PUBLIC_INTERNAL_DOCS_ORIGIN', internalOrigin);
+ vi.stubEnv('NEXT_PUBLIC_DOCS_ACCESS_CHECK_ORIGIN', probeOrigin);
jsdom.reconfigure({
url: 'https://astryx.atmeta.com/components/Button?tab=props',
});
@@ -127,6 +129,62 @@ describe('InternalDocsPrompt', () => {
expect(layout).not.toContain('<InternalDocsPrompt');
});
+ it.each([
+ ['neither origin', undefined, undefined],
+ ['only the docs origin', internalOrigin, undefined],
+ ['only the probe origin', undefined, probeOrigin],
+ ['an empty docs origin', '', probeOrigin],
+ ['a malformed probe origin', internalOrigin, 'not a url'],
+ ['a non-https probe origin', internalOrigin, 'http://probe.example.test'],
+ ])(
+ 'never probes or renders with %s configured',
+ async (_, docsOrigin, accessCheckOrigin) => {
+ vi.stubEnv('NEXT_PUBLIC_INTERNAL_DOCS_ORIGIN', docsOrigin);
+ vi.stubEnv('NEXT_PUBLIC_DOCS_ACCESS_CHECK_ORIGIN', accessCheckOrigin);
+ await loadPrompt();
+ const append = vi.spyOn(document.body, 'append');
+ await mount();
+ await act(async () => vi.advanceTimersByTime(5000));
+ expect(append).not.toHaveBeenCalled();
+ expect(document.querySelector('iframe')).toBeNull();
+ expect(prompt()).toBeNull();
+ if (!docsOrigin) {
+ expect(href('/docs', 'a=1')).toBeUndefined();
+ }
+ },
+ );
+
+ it('keeps only the public Canary notice when the origins are not configured', async () => {
+ vi.stubEnv('NEXT_PUBLIC_DOCS_TARGET', 'canary');
+ vi.stubEnv('NEXT_PUBLIC_INTERNAL_DOCS_ORIGIN', undefined);
+ vi.stubEnv('NEXT_PUBLIC_DOCS_ACCESS_CHECK_ORIGIN', undefined);
+ await loadPrompt();
+ await mount();
+ await act(async () => vi.advanceTimersByTime(5000));
+ expect(document.querySelector('iframe')).toBeNull();
+ expect(prompt()?.textContent).toContain("You're viewing Canary docs");
+ expect(prompt()?.outerHTML).not.toMatch(
+ /Meta internal|Meta-specific components/,
+ );
+ });
+
+ it('uses the exact configured origins, without a trailing path', async () => {
+ vi.stubEnv('NEXT_PUBLIC_INTERNAL_DOCS_ORIGIN', `${internalOrigin}/`);
+ vi.stubEnv('NEXT_PUBLIC_DOCS_ACCESS_CHECK_ORIGIN', ` ${probeOrigin}/x `);
+ await loadPrompt();
+ await mount();
+ const target = frame();
+ expect(target.src).toBe(
+ `${probeOrigin}/embed/access-check?parent_origin=https%3A%2F%2Fastryx.atmeta.com`,
+ );
+ showPrompt();
+ expect(
+ screen
+ .getByRole('link', {name: 'Meta internal docs'})
+ .getAttribute('href'),
+ ).toBe(`${internalOrigin}/components/Button?tab=props`);
+ });
+
it('does not start another probe inside an embedded document', async () => {
const parentFrame = document.createElement('iframe');
document.body.append(parentFrame);
@@ -227,9 +285,9 @@ describe('InternalDocsPrompt', () => {
it.each([
'https://evil.example',
- 'https://codebunny.internalmeta.com.evil.example',
- 'http://codebunny.internalmeta.com',
- 'https://astryx.internalmeta.com',
+ 'https://probe.example.test.evil.example',
+ 'http://probe.example.test',
+ 'https://docs.example.test',
'null',
])('ignores messages from the wrong origin: %s', async origin => {
await mount();
diff --git a/apps/docsite/src/components/InternalDocsPrompt.tsx b/apps/docsite/src/components/InternalDocsPrompt.tsx
index 1b28b00666..e9a72f5d2b 100644
--- a/apps/docsite/src/components/InternalDocsPrompt.tsx
+++ b/apps/docsite/src/components/InternalDocsPrompt.tsx
@@ -3,7 +3,8 @@
'use client';
/**
- * @input Build target, exact-origin reachability, and the current docs view
+ * @input Build target, configured docs origin, exact-origin reachability, and
+ * the current docs view
* @output The internal-docs banner after reachability, otherwise the public Canary banner
* @position Root-owned detection; banner content lives in the page shell
*/
@@ -31,7 +32,13 @@ export function InternalDocsReachabilityProvider({
);
}
-export function internalDocsHref(pathname: string, search: string): string {
+export function internalDocsHref(
+ pathname: string,
+ search: string,
+): string | undefined {
+ if (!INTERNAL_DOCS_ORIGIN) {
+ return undefined;
+ }
// Shared route families use the same topic/name/slug semantics. Public-only
// pages (blog, community, changelog, preview) have no same-path counterpart.
const hasCounterpart =
diff --git a/apps/docsite/src/lib/useInternalDocsPrompt.ts b/apps/docsite/src/lib/useInternalDocsPrompt.ts
index 3064f1c5e7..88f27b3245 100644
--- a/apps/docsite/src/lib/useInternalDocsPrompt.ts
+++ b/apps/docsite/src/lib/useInternalDocsPrompt.ts
@@ -3,9 +3,15 @@
'use client';
/**
- * @input A top-level page and an anonymous iframe's exact-origin reachability message
+ * @input Build-time docs and probe origins, a top-level page, and an anonymous
+ * iframe's exact-origin reachability message
* @output A fail-closed, once-per-page-load reachability result
* @position Client-only detection shared across root-layout remounts
+ *
+ * Both origins are deployment configuration, read from
+ * NEXT_PUBLIC_INTERNAL_DOCS_ORIGIN and NEXT_PUBLIC_DOCS_ACCESS_CHECK_ORIGIN at
+ * build time. A build without both (every fork and local build by default)
+ * never probes and never shows the prompt.
*/
import {useSyncExternalStore} from 'react';
@@ -15,8 +21,33 @@ export const ALLOWED_PARENT_ORIGINS: readonly string[] = [
'https://astryx-git-feat-docs-internal-network-prompt-fbopensource.vercel.app',
'https://astryx-canary.vercel.app',
];
-export const INTERNAL_DOCS_ORIGIN = 'https://astryx.internalmeta.com';
-export const ACCESS_CHECK_ORIGIN = 'https://codebunny.internalmeta.com';
+
+/**
+ * The exact origin of a configured absolute https URL, or undefined when the
+ * value is missing, malformed, or not https: a bad value disables the prompt
+ * rather than probing or linking somewhere unintended.
+ */
+export function configuredOrigin(
+ value: string | undefined,
+): string | undefined {
+ if (!value?.trim()) {
+ return undefined;
+ }
+ try {
+ const url = new URL(value.trim());
+ return url.protocol === 'https:' ? url.origin : undefined;
+ } catch {
+ return undefined;
+ }
+}
+
+// Each variable is read by its literal name so the build inlines it.
+export const INTERNAL_DOCS_ORIGIN = configuredOrigin(
+ process.env.NEXT_PUBLIC_INTERNAL_DOCS_ORIGIN,
+);
+export const ACCESS_CHECK_ORIGIN = configuredOrigin(
+ process.env.NEXT_PUBLIC_DOCS_ACCESS_CHECK_ORIGIN,
+);
export const ACCESS_CHECK_MESSAGE_TYPE = 'codebunny:access-check:v1';
const listeners = new Set<() => void>();
@@ -34,6 +65,12 @@ function publishReachability(next: boolean) {
function startCheck() {
attempted = true;
+ // Without both configured origins there is nothing to probe or link to.
+ const accessCheckOrigin = ACCESS_CHECK_ORIGIN;
+ if (!accessCheckOrigin || !INTERNAL_DOCS_ORIGIN) {
+ return;
+ }
+
// Embedded documents, including playground previews, must not probe again.
if (window.top !== window) {
return;
@@ -53,7 +90,7 @@ function startCheck() {
frame.setAttribute('sandbox', 'allow-scripts allow-same-origin');
frame.title = 'Astryx documentation reachability check';
frame.referrerPolicy = 'no-referrer';
- frame.src = `${ACCESS_CHECK_ORIGIN}/embed/access-check?parent_origin=${encodeURIComponent(parentOrigin)}`;
+ frame.src = `${accessCheckOrigin}/embed/access-check?parent_origin=${encodeURIComponent(parentOrigin)}`;
let loaded = false;
let received = false;
@@ -73,7 +110,7 @@ function startCheck() {
};
const onMessage = (event: MessageEvent) => {
if (
- event.origin !== ACCESS_CHECK_ORIGIN ||
+ event.origin !== accessCheckOrigin ||
event.source !== frame.contentWindow ||
event.data?.type !== ACCESS_CHECK_MESSAGE_TYPE ||
event.data?.reachable !== true