Skip to content

Commit 2b3ec9e

Browse files
alexcarpentermaxyingerclaude
authored
feat(repo): add Mosaic docs site (#10862)
Co-authored-by: Max Yinger <35983235+maxyinger@users.noreply.github.com> Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
1 parent 3c36ad4 commit 2b3ec9e

79 files changed

Lines changed: 3405 additions & 14 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.changeset/mosaic-docs-scaffold.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
---
2+
---

‎package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@
1313
"dev": "TURBO_UI=0 FORCE_COLOR=1 turbo dev --filter=@clerk/* --filter=!@clerk/expo --filter=!@clerk/expo-native-components --filter=!@clerk/tanstack-react-start --filter=!@clerk/chrome-extension",
1414
"dev:fe-libs": "TURBO_UI=0 FORCE_COLOR=1 turbo dev --filter=@clerk/clerk-js --filter=@clerk/ui --filter=@clerk/shared",
1515
"dev:js": "TURBO_UI=0 FORCE_COLOR=1 turbo dev:current --filter=@clerk/clerk-js",
16+
"dev:mosaic-docs": "TURBO_UI=0 FORCE_COLOR=1 turbo dev --filter=@clerk/mosaic-docs",
1617
"dev:sandbox": "TURBO_UI=0 FORCE_COLOR=1 turbo dev:sandbox:serve",
1718
"dev:swingset": "pnpm --filter @clerk/shared build && TURBO_UI=0 FORCE_COLOR=1 turbo dev --filter=@clerk/swingset --filter=@clerk/shared",
1819
"format": "turbo format && node scripts/format-non-workspace.mjs",

‎packages/mosaic-docs/.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
src/generated

‎packages/mosaic-docs/AGENTS.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
<!-- BEGIN:nextjs-agent-rules -->
2+
3+
## This is NOT the Next.js you know
4+
5+
This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` (resolved from this file's directory; in monorepos the `next` package may not be visible from the repo root) before writing any code. Heed deprecation notices.
6+
7+
This block is written and re-added by `next dev` — verify at `node_modules/next/dist/server/lib/generate-agent-files.js`. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.
8+
9+
<!-- END:nextjs-agent-rules -->

‎packages/mosaic-docs/README.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
# Mosaic docs
2+
3+
The documentation site for [`@clerk/mosaic`](../mosaic), Clerk's design system.
4+
5+
## Development
6+
7+
From the repository root:
8+
9+
```sh
10+
pnpm dev:mosaic-docs
11+
```
12+
13+
This builds `@clerk/mosaic` and starts the site at http://localhost:6021.
14+
15+
## Layout
16+
17+
The site is split into layers so the docs system can be reused. `src/layers.test.ts` enforces the import rules.
18+
19+
| Folder | Contains | May import |
20+
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ------------- |
21+
| `src/core` | Pure functions and the doc schema: Markdown output, llms.txt, content negotiation, highlighting, the TOC and the remark headings plugin | packages only |
22+
| `src/ui` | React parts and `styles.css` | `src/core` |
23+
| `src/next` | Next.js adapters, such as `markdownProxy` | `src/core` |
24+
| everything else | Mosaic-specific content, data, examples and pages | anything |
25+
26+
## Acknowledgements
27+
28+
The site's design and features were inspired by [Blume](https://github.com/haydenbleasel/blume) and [Fumadocs](https://github.com/fuma-nama/fumadocs).
Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
import { fileURLToPath } from 'node:url';
2+
3+
import createMDX from '@next/mdx';
4+
5+
/** @type {import('next').NextConfig} */
6+
const nextConfig = {
7+
pageExtensions: ['ts', 'tsx', 'mdx'],
8+
headers() {
9+
return [{ source: '/:path*', headers: [{ key: 'X-Robots-Tag', value: 'noindex' }] }];
10+
},
11+
redirects() {
12+
return [
13+
{ source: '/docs', destination: '/docs/setup', permanent: true },
14+
{ source: '/docs.md', destination: '/docs/setup.md', permanent: true },
15+
];
16+
},
17+
rewrites() {
18+
return [{ source: '/docs/:path*.md', destination: '/llms.mdx/docs/:path*' }];
19+
},
20+
};
21+
22+
const withMDX = createMDX({
23+
options: {
24+
remarkPlugins: [fileURLToPath(new URL('./src/core/remark-headings.ts', import.meta.url))],
25+
},
26+
});
27+
28+
export default withMDX(nextConfig);

‎packages/mosaic-docs/package.json‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
{
2+
"name": "@clerk/mosaic-docs",
3+
"version": "0.0.0",
4+
"private": true,
5+
"type": "module",
6+
"scripts": {
7+
"build": "pnpm generate && next build",
8+
"dev": "pnpm generate && next dev --port 6021",
9+
"format": "node ../../scripts/format-package.mjs",
10+
"format:check": "node ../../scripts/format-package.mjs --check",
11+
"generate": "node scripts/generate-docs.mjs",
12+
"lint": "oxlint -c ../../oxlint.config.mjs src scripts",
13+
"test": "node --test 'scripts/*.test.mjs' 'src/**/*.test.ts'",
14+
"typecheck": "pnpm generate && next typegen && tsc --noEmit"
15+
},
16+
"dependencies": {
17+
"@clerk/mosaic": "workspace:*",
18+
"@mdx-js/loader": "^3.1.1",
19+
"@mdx-js/react": "^3.1.1",
20+
"@next/mdx": "^16.4.3",
21+
"estree-util-value-to-estree": "^3.5.0",
22+
"github-slugger": "^2.0.0",
23+
"mdast-util-to-string": "^4.0.0",
24+
"next": "^16.4.3",
25+
"react": "catalog:react",
26+
"react-dom": "catalog:react",
27+
"shiki": "^4.1.0",
28+
"unist-util-visit": "^5.2.0"
29+
},
30+
"devDependencies": {
31+
"@mdx-js/mdx": "^3.1.1",
32+
"@tailwindcss/postcss": "^4.3.0",
33+
"@tailwindcss/typography": "^0.5.20",
34+
"@types/mdast": "^4.0.4",
35+
"@types/mdx": "^2.0.14",
36+
"@types/react": "catalog:react",
37+
"@types/react-dom": "catalog:react",
38+
"tailwindcss": "^4.3.0",
39+
"typescript": "catalog:repo"
40+
}
41+
}
Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
export default {
2+
plugins: {
3+
'@tailwindcss/postcss': {},
4+
},
5+
};
Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
import { globSync, mkdirSync, realpathSync, writeFileSync } from 'node:fs';
2+
import { dirname, relative } from 'node:path';
3+
import { fileURLToPath } from 'node:url';
4+
5+
const DOC_PATH = /^src\/(?:(components|primitives)\/([a-z0-9-]+)\/\2|(hooks)\/(use-[a-z0-9-]+))\.doc\.ts$/;
6+
const EXCLUDED = new Set([
7+
'components/branding',
8+
'components/captcha',
9+
'components/clerk-logo',
10+
'components/scroll-area',
11+
'hooks/use-mosaic-environment',
12+
'hooks/use-mosaic-experimental',
13+
'hooks/use-mosaic-router',
14+
'hooks/use-mosaic-support-email',
15+
]);
16+
17+
export function toEntries(paths) {
18+
const entries = paths.map(toPosix).map(path => {
19+
const match = DOC_PATH.exec(path);
20+
if (!match) {
21+
throw new Error(`Unexpected doc location: ${path}`);
22+
}
23+
const kind = match[1] ?? match[3];
24+
const slug = match[2] ?? match[4];
25+
return { kind, slug, path: path.replace(/\.ts$/, '') };
26+
});
27+
28+
return entries
29+
.filter(({ kind, slug }) => !EXCLUDED.has(`${kind}/${slug}`))
30+
.sort((a, b) => a.kind.localeCompare(b.kind) || a.slug.localeCompare(b.slug));
31+
}
32+
33+
export function renderModule(dir, entries) {
34+
const mosaicDir = toPosix(dir);
35+
const imports = entries.map((entry, index) => `import doc${index} from '${mosaicDir}/${entry.path}';`);
36+
const rows = entries.map((entry, index) => ` { kind: '${entry.kind}', slug: '${entry.slug}', doc: doc${index} },`);
37+
return [
38+
`import type { ComponentDoc, HookDoc } from '${mosaicDir}/src/docs-schema';`,
39+
...imports,
40+
'',
41+
'type Props = Record<string, unknown>;',
42+
'',
43+
'export interface DocEntry {',
44+
" kind: 'components' | 'primitives' | 'hooks';",
45+
' slug: string;',
46+
' doc: ComponentDoc<Record<string, Props>> | HookDoc<Props, Props>;',
47+
'}',
48+
'',
49+
'export const docEntries: DocEntry[] = [',
50+
...rows,
51+
'];',
52+
'',
53+
].join('\n');
54+
}
55+
56+
function toPosix(path) {
57+
return path.replaceAll('\\', '/');
58+
}
59+
60+
if (import.meta.main) {
61+
const mosaicDir = realpathSync(dirname(fileURLToPath(import.meta.resolve('@clerk/mosaic/package.json'))));
62+
const outFile = fileURLToPath(new URL('../src/generated/docs.ts', import.meta.url));
63+
const entries = toEntries(globSync('src/{components,primitives,hooks}/**/*.doc.ts', { cwd: mosaicDir }));
64+
mkdirSync(dirname(outFile), { recursive: true });
65+
writeFileSync(outFile, renderModule(relative(dirname(outFile), mosaicDir), entries));
66+
console.log(`Generated ${entries.length} docs`);
67+
}
Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
import assert from 'node:assert/strict';
2+
import { test } from 'node:test';
3+
4+
import { renderModule, toEntries } from './generate-docs.mjs';
5+
6+
test('maps doc paths to a kind and slug', () => {
7+
assert.deepEqual(
8+
toEntries([
9+
'src/primitives/accordion/accordion.doc.ts',
10+
'src/hooks/use-pending-action.doc.ts',
11+
'src/components/button/button.doc.ts',
12+
]),
13+
[
14+
{ kind: 'components', slug: 'button', path: 'src/components/button/button.doc' },
15+
{ kind: 'hooks', slug: 'use-pending-action', path: 'src/hooks/use-pending-action.doc' },
16+
{ kind: 'primitives', slug: 'accordion', path: 'src/primitives/accordion/accordion.doc' },
17+
],
18+
);
19+
});
20+
21+
test('leaves out docs the site does not publish', () => {
22+
assert.deepEqual(toEntries(['src/components/captcha/captcha.doc.ts', 'src/components/button/button.doc.ts']), [
23+
{ kind: 'components', slug: 'button', path: 'src/components/button/button.doc' },
24+
]);
25+
});
26+
27+
test('rejects a doc outside the documented locations', () => {
28+
assert.throws(
29+
() => toEntries(['src/components/button/parts/icon.doc.ts']),
30+
/src\/components\/button\/parts\/icon\.doc\.ts/,
31+
);
32+
assert.throws(() => toEntries(['src/blocks/sign-in/sign-in.doc.ts']), /sign-in\.doc\.ts/);
33+
});
34+
35+
test('renders one typed import per doc', () => {
36+
const source = renderModule('../../../mosaic', [
37+
{ kind: 'components', slug: 'button', path: 'src/components/button/button.doc' },
38+
{ kind: 'hooks', slug: 'use-form', path: 'src/hooks/use-form.doc' },
39+
]);
40+
assert.match(source, /import type \{ ComponentDoc, HookDoc \} from '\.\.\/\.\.\/\.\.\/mosaic\/src\/docs-schema';/);
41+
assert.match(source, /import doc0 from '\.\.\/\.\.\/\.\.\/mosaic\/src\/components\/button\/button\.doc';/);
42+
assert.match(source, /import doc1 from '\.\.\/\.\.\/\.\.\/mosaic\/src\/hooks\/use-form\.doc';/);
43+
assert.match(source, /\{ kind: 'components', slug: 'button', doc: doc0 \}/);
44+
assert.match(source, /\{ kind: 'hooks', slug: 'use-form', doc: doc1 \}/);
45+
});
46+
47+
test('accepts Windows doc paths', () => {
48+
assert.deepEqual(toEntries(['src\\components\\button\\button.doc.ts']), [
49+
{ kind: 'components', slug: 'button', path: 'src/components/button/button.doc' },
50+
]);
51+
});
52+
53+
test('renders forward-slash imports from a Windows Mosaic directory', () => {
54+
const source = renderModule('..\\..\\mosaic', [
55+
{ kind: 'components', slug: 'button', path: 'src/components/button/button.doc' },
56+
]);
57+
assert.match(source, /from '\.\.\/\.\.\/mosaic\/src\/docs-schema';/);
58+
assert.match(source, /import doc0 from '\.\.\/\.\.\/mosaic\/src\/components\/button\/button\.doc';/);
59+
});

0 commit comments

Comments
 (0)