Skip to content

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

TypeScript

docs(cli): a Use integrations guide, so consumer queries find consumer docs first (#7153)

Joey0bf23bdbf686
diff --git a/.changeset/search-consumer-ranking.md b/.changeset/search-consumer-ranking.md
new file mode 100644
index 0000000000..fc645dae8f
--- /dev/null
+++ b/.changeset/search-consumer-ranking.md
@@ -0,0 +1,13 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[docs] A new "Use integrations" guide, so consumer queries find consumer docs first, not authoring content.
+
+@josephfarina
+
+Added a "Use integrations" guide (`use-integrations.doc.mjs`) that covers
+discovering, installing, and using integration packages in an app. Search
+now ranks it above authoring and API-function docs for consumer-phrased
+queries like "add an integration" or "install a package". Authoring
+queries like "build an integration" still rank authoring content first.
diff --git a/apps/docsite/src/__tests__/route-resolution.test.ts b/apps/docsite/src/__tests__/route-resolution.test.ts
index d030ff1dee..1824ff7e64 100644
--- a/apps/docsite/src/__tests__/route-resolution.test.ts
+++ b/apps/docsite/src/__tests__/route-resolution.test.ts
@@ -91,7 +91,8 @@ describe('route resolution', () => {
// The Guide section as it was before the CLI integration guide and the
// other topics were split into short guides. `styling-overview` and
// `cli-host-entry` are topics added since; `global` is the Global mode
- // page; `authoring` holds what CLI Integrations and Writing docs did.
+ // page; `authoring` holds what CLI Integrations and Writing docs did;
+ // `use-integrations` is the guide for apps that install one.
const sidebarGuides = docTopics
.filter(d => d.category === 'guide' && d.topic !== 'getting-started')
.map(d => d.topic)
@@ -112,6 +113,7 @@ describe('route resolution', () => {
'styling-libraries',
'styling-overview',
'theme',
+ 'use-integrations',
'working-with-ai',
].sort(),
);
@@ -121,7 +123,9 @@ describe('route resolution', () => {
expect(pageBySlug.get('authoring')?.category).toBe('guide');
let guides = 0;
for (const route of docsTreeRoutes) {
- if (!route.startsWith('authoring/')) {continue;}
+ if (!route.startsWith('authoring/')) {
+ continue;
+ }
guides++;
const slug = route.replaceAll('/', '-');
expect(pageBySlug.has(slug), slug).toBe(false);
@@ -150,7 +154,9 @@ describe('route resolution', () => {
expect(docRedirects['cli-global']).toBe('/docs/global');
expect(docRedirects['cli-install-once']).toBe('/docs/global');
for (const route of docsTreeRoutes) {
- if (!route.startsWith('global/')) {continue;}
+ if (!route.startsWith('global/')) {
+ continue;
+ }
const slug = route.replaceAll('/', '-');
expect(docRedirects[slug], slug).toMatch(/^\/docs\/global#/);
}
diff --git a/packages/cli/assets/docs/use-integrations.doc.mjs b/packages/cli/assets/docs/use-integrations.doc.mjs
new file mode 100644
index 0000000000..097bacd486
--- /dev/null
+++ b/packages/cli/assets/docs/use-integrations.doc.mjs
@@ -0,0 +1,120 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').ReferenceDoc} */
+
+export const docs = {
+ type: 'generic',
+ name: 'use-integrations',
+ title: 'Use integrations',
+ category: 'guide',
+ description:
+ 'Install, discover, and use integration packages that add components, templates, themes, and docs to your app.',
+ keywords: [
+ 'install an integration',
+ 'add an integration',
+ 'install a package',
+ 'use an integration',
+ 'discover integrations',
+ 'integration',
+ 'package',
+ 'third party',
+ 'plugin',
+ 'extension',
+ ],
+
+ sections: [
+ {
+ title: 'Discover integrations',
+ content: [
+ {
+ type: 'prose',
+ text: 'Integration packages extend Astryx with extra components, templates, themes, docs, and codemods. They are published as regular npm packages.',
+ },
+ {
+ type: 'prose',
+ text: 'Search for what you need:',
+ },
+ {
+ type: 'code',
+ lang: 'bash',
+ code: 'astryx search carousel\nastryx discover',
+ },
+ {
+ type: 'prose',
+ text: '`search` looks across everything the CLI knows (components, docs, templates, themes, and hooks), so a word like "carousel" finds it whether it is a component, a template, or a doc page. `discover` lists every integration the project has, and, with a discover source, packages it could add.',
+ },
+ ],
+ },
+ {
+ title: 'Install an integration',
+ content: [
+ {
+ type: 'prose',
+ text: 'Install the package with your package manager. Integrations autolink: the CLI finds them among your dependencies, so installing is all it takes:',
+ },
+ {
+ type: 'code',
+ lang: 'bash',
+ code: 'npm install @acme/brand-integration',
+ },
+ {
+ type: 'prose',
+ text: 'Run `astryx doctor` to confirm everything is wired up. If you need to load a package that is not a direct dependency, add it explicitly to `astryx.config.mjs`:',
+ },
+ {
+ type: 'code',
+ lang: 'js',
+ label: 'Optional: explicit config entry',
+ code: "export default {\n integrations: ['@acme/brand-integration'],\n};",
+ },
+ ],
+ },
+ {
+ title: 'Use what it adds',
+ content: [
+ {
+ type: 'prose',
+ text: 'Once installed, the integration\'s contributions appear alongside Core:',
+ },
+ {
+ type: 'list',
+ style: 'unordered',
+ items: [
+ '`astryx component --list` shows its components next to Core components.',
+ '`astryx template --list` includes its page and block templates.',
+ '`astryx theme list` lists its themes; add one with `astryx theme add <slug> --package @acme/brand-integration`.',
+ '`astryx docs` shows any guides it provides.',
+ '`astryx search <query>` finds everything, from every installed integration.',
+ ],
+ },
+ {
+ type: 'prose',
+ text: 'Import components at the subpath the integration documents. Run `astryx component <Name>` to see the exact import:',
+ },
+ {
+ type: 'code',
+ lang: 'jsx',
+ code: "import {AcmeCarousel} from '@acme/brand-integration/components/AcmeCarousel';",
+ },
+ {
+ type: 'prose',
+ text: 'For themes, see {@link generic:use-a-theme}. To build an integration of your own, see {@link namespace:authoring}.',
+ },
+ ],
+ },
+ {
+ title: 'Check for problems',
+ content: [
+ {
+ type: 'prose',
+ text: 'Run `astryx doctor` to see integration issues: missing roots, invalid contributions, or a CLI version mismatch. The doctor check is the one place every issue for every package is listed.',
+ },
+ {
+ type: 'code',
+ lang: 'bash',
+ code: 'astryx doctor',
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/cli/test/search-consumer-ranking.test.mjs b/packages/cli/test/search-consumer-ranking.test.mjs
new file mode 100644
index 0000000000..14cbc3b678
--- /dev/null
+++ b/packages/cli/test/search-consumer-ranking.test.mjs
@@ -0,0 +1,53 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Consumer queries rank consumer docs above authoring docs.
+ *
+ * An app builder searching "add an integration" or "use a theme" should find
+ * consumer guides in the first 3 results, not the authoring reference or the
+ * API function docs. Authoring queries ("create an integration", "build an
+ * integration") should still rank authoring content first.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {search} from '../api/search/search.mjs';
+
+// Each case: [query, expected-name-in-top-3, must-NOT-be-first]
+/** @type {Array<[string, string, string?]>} */
+const CONSUMER_QUERIES = [
+ ['add an integration', 'use-integrations'],
+ ['use an integration', 'use-integrations'],
+ ['install a package', 'use-integrations'],
+ ['discover integrations', 'use-integrations'],
+ ['install an integration', 'use-integrations'],
+ ['how to use a theme', 'use-a-theme'],
+];
+
+/** @type {Array<[string, string]>} */
+const AUTHORING_QUERIES = [
+ ['build an integration', 'authoring'],
+ ['create an integration', 'authoring'],
+];
+
+describe('consumer queries rank consumer docs first', () => {
+ for (const [query, expected] of CONSUMER_QUERIES) {
+ it(`"${query}" ranks "${expected}" first`, async () => {
+ const res = await search(query);
+ const first = res.data.results[0]?.name;
+ expect(first, `first for "${query}": ${first}`).toBe(expected);
+ });
+ }
+});
+
+describe('authoring queries still rank authoring content first', () => {
+ for (const [query, expected] of AUTHORING_QUERIES) {
+ it(`"${query}" ranks "${expected}" in the top 3`, async () => {
+ const res = await search(query);
+ const top3 = res.data.results.slice(0, 3).map(r => r.name);
+ expect(
+ top3.some(name => name.startsWith(expected)),
+ `top 3 for "${query}": ${top3.join(', ')} should contain a ${expected} result`,
+ ).toBe(true);
+ });
+ }
+});