create-graphql-markdown-docs 1.0.0 → 1.1.0

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/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # create-graphql-markdown-docs
2
2
 
3
- Interactive CLI that either creates a ready-to-run [GraphQL Markdown](https://graphql-markdown.dev) API reference site (Nuxt or Docusaurus) or adds GraphQL-Markdown to an existing documentation site. The Nuxt preset is built on the [`@graphql-markdown/nuxt-theme`](https://github.com/graphql-markdown/graphql-markdown/tree/main/packages/nuxt-theme) layer.
3
+ Interactive CLI that either creates a new [GraphQL Markdown](https://graphql-markdown.dev) project (a ready-to-run Nuxt or Docusaurus API reference site, or plain Markdown or MDX output) or adds GraphQL-Markdown to an existing documentation site. The Nuxt preset is built on the [`@graphql-markdown/nuxt-theme`](https://github.com/graphql-markdown/graphql-markdown/tree/main/packages/nuxt-theme) layer.
4
4
 
5
5
  Full guide: [graphql-markdown.dev/docs/get-started](https://graphql-markdown.dev/docs/get-started).
6
6
 
@@ -39,7 +39,7 @@ In wire mode the CLI:
39
39
  1. Detects the framework from `package.json`, or asks you to choose one (`generic` for anything unlisted).
40
40
  2. Asks for the schema (a path, glob or URL, written as you enter it) and the output folder. The output folder is always asked, never guessed.
41
41
  3. Suggests a link root for the generated pages.
42
- 4. Writes a `.graphqlrc` file and a `docs:api` script that runs `gqlmd graphql-to-doc`.
42
+ 4. Writes a `.graphqlrc` file and a `gqlmd` script that runs `gqlmd graphql-to-doc`.
43
43
  5. Prints the next step for your framework, such as adding a sidebar or navigation entry.
44
44
 
45
45
  It never edits your framework configuration files and never overwrites existing files. If the project already has a GraphQL config, the CLI prints the block to merge into it instead. It installs nothing unless you pass `--install`; otherwise it prints the install command. Use `--dry-run` to see what it would write without writing anything.
@@ -54,19 +54,20 @@ With `--yes`, `--schema` and `--output` are required, and so is `--framework` wh
54
54
 
55
55
  ### Supported frameworks (existing sites)
56
56
 
57
- | Framework | Typical output folder | Notes |
58
- | --------------- | ---------------------- | --------------------------------------------------------- |
59
- | Docusaurus | `docs/api` | Router links; the suggested link root follows the route. |
60
- | Nuxt | `content/api` | Router links; the suggested link root follows the route. |
61
- | Astro Starlight | `src/content/docs/api` | Set `--site-base` if the site is served under a sub-path. |
62
- | Fumadocs | `content/docs/api` | Router links; the suggested link root follows the route. |
63
- | Vocs | `docs/pages/api` | Router links; the suggested link root follows the route. |
64
- | HonKit | `api` | Set `--site-base` if the site is served under a sub-path. |
65
- | Hugo | `content/api` | Set `--site-base` if the site is served under a sub-path. |
66
- | MkDocs | `docs/api` | Links relative to pages. |
67
- | DocFX | `docs/api` | Links relative to pages. |
68
- | mdBook | `src/api` | Links relative to pages. |
69
- | Generic | Any folder you choose | Any Markdown/MDX site — you set the link root. |
57
+ | Framework | Typical output folder | Notes |
58
+ | --------------- | ---------------------- | ------------------------------------------------------------------------------------ |
59
+ | Docusaurus | `docs/api` | Router links; the suggested link root follows the route. |
60
+ | Nuxt | `content/api` | Router links; the suggested link root follows the route. |
61
+ | Astro Starlight | `src/content/docs/api` | Set `--site-base` if the site is served under a sub-path. |
62
+ | Fumadocs | `content/docs/api` | Router links; the suggested link root follows the route. |
63
+ | Vocs | `docs/pages/api` | Router links; the suggested link root follows the route. |
64
+ | HonKit | `api` | Set `--site-base` if the site is served under a sub-path. |
65
+ | Hugo | `content/api` | Set `--site-base` if the site is served under a sub-path. |
66
+ | MkDocs | `docs/api` | Links relative to pages. |
67
+ | DocFX | `docs/api` | Links relative to pages. |
68
+ | mdBook | `src/api` | Links relative to pages. |
69
+ | Generic MDX | Any folder you choose | Framework-neutral `.mdx` pages (plain HTML, no components); links relative to pages. |
70
+ | Generic | Any folder you choose | Any Markdown/MDX site — you set the link root. |
70
71
 
71
72
  ## Schema sources
72
73
 
@@ -97,17 +98,17 @@ npm create graphql-markdown-docs@latest -- --yes --dir ./my-docs --schema ./sche
97
98
 
98
99
  #### Shared
99
100
 
100
- | Flag | Description |
101
- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
102
- | `[dir]`, `-d, --dir <path>` | Target folder (default: ask, or the current folder with `--existing`). |
103
- | `--new` \| `--existing` | Force scaffold or wire mode (default: picked from the folder). |
104
- | `--framework <name>` | Scaffold: `nuxt` \| `docusaurus` (default `nuxt`). Wire: `docusaurus` \| `starlight` \| `fumadocs` \| `vocs` \| `honkit` \| `hugo` \| `mkdocs` \| `docfx` \| `mdbook` \| `nuxt` \| `generic`. |
105
- | `--schema <source>` | Schema source: `<path\|url\|git:\|github:>`. See the table above. |
106
- | `--pm <name>` | Package manager: `npm` \| `pnpm` \| `yarn` \| `bun`. Otherwise detected from the invoking command, then from lockfiles. |
107
- | `--install` / `--no-install` | Install dependencies (or skip it). Wire mode installs nothing unless `--install` is passed. |
108
- | `-y, --yes` | Accept defaults and skip all prompts. |
109
- | `-h, --help` | Show usage and exit. |
110
- | `-v, --version` | Print the CLI version and exit. |
101
+ | Flag | Description |
102
+ | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
103
+ | `[dir]`, `-d, --dir <path>` | Target folder (default: ask, or the current folder with `--existing`). |
104
+ | `--new` \| `--existing` | Force scaffold or wire mode (default: picked from the folder). |
105
+ | `--framework <name>` | Scaffold: `nuxt` \| `docusaurus` \| `markdown` \| `mdx` (default `nuxt`; `generic` is accepted as `markdown`). Wire: `docusaurus` \| `starlight` \| `fumadocs` \| `vocs` \| `honkit` \| `hugo` \| `mkdocs` \| `docfx` \| `mdbook` \| `nuxt` \| `mdx` \| `generic` (`markdown` is accepted as `generic`). |
106
+ | `--schema <source>` | Schema source: `<path\|url\|git:\|github:>`. See the table above. |
107
+ | `--pm <name>` | Package manager: `npm` \| `pnpm` \| `yarn` \| `bun`. Otherwise detected from the invoking command, then from lockfiles. |
108
+ | `--install` / `--no-install` | Install dependencies (or skip it). Wire mode installs nothing unless `--install` is passed. |
109
+ | `-y, --yes` | Accept defaults and skip all prompts. |
110
+ | `-h, --help` | Show usage and exit. |
111
+ | `-v, --version` | Print the CLI version and exit. |
111
112
 
112
113
  #### Scaffold only
113
114
 
@@ -126,7 +127,7 @@ npm create graphql-markdown-docs@latest -- --yes --dir ./my-docs --schema ./sche
126
127
  | `--output <folder>` | Folder for the generated docs, relative to the project. |
127
128
  | `--link-root <route>` | Route prefix used in generated links. |
128
129
  | `--site-base <route>` | Base path the site is served from. |
129
- | `--script <name>` | `package.json` script to add (default: `docs:api`). |
130
+ | `--script <name>` | `package.json` script to add (default: `gqlmd`). |
130
131
  | `--dry-run` | Show what would be written without writing it. |
131
132
 
132
133
  ## What's included
@@ -150,6 +151,12 @@ With `--framework docusaurus`, the scaffold replaces the standalone `graphql-mar
150
151
 
151
152
  Then run `npm run doc` to generate the docs and `npm start` to serve them.
152
153
 
154
+ ## Telemetry
155
+
156
+ The scaffolder reports one anonymous event per run (scaffold or wire): the framework, mode and schema loader type, with custom strings, URLs and paths masked. No schema content is sent. Nothing is sent on `--dry-run`. The first run shows a notice.
157
+
158
+ Opt out with the `--no-telemetry` flag, `DO_NOT_TRACK=1`, or `gqlmd telemetry disable`. See [what is collected](https://graphql-markdown.dev/docs/telemetry).
159
+
153
160
  ## Documentation
154
161
 
155
162
  - [`@graphql-markdown/nuxt-theme`](https://github.com/graphql-markdown/graphql-markdown/tree/main/packages/nuxt-theme) — the layer this scaffolds, including the full customization/swizzling reference.
package/lib/create.mjs CHANGED
@@ -7,6 +7,7 @@ import * as prompts from "@clack/prompts";
7
7
 
8
8
  import {
9
9
  DEFAULT_FRAMEWORK,
10
+ FRAMEWORK_ALIASES,
10
11
  FRAMEWORKS,
11
12
  WIRE_FRAMEWORKS,
12
13
  } from "./frameworks/index.mjs";
@@ -31,10 +32,11 @@ import {
31
32
  isRemoteSchemaSource,
32
33
  validateGraphQLSchema,
33
34
  } from "./schema.mjs";
35
+ import { reportTelemetry } from "./telemetry.mjs";
34
36
  import { WIRE_STEPS, printWireOutro } from "./wire/steps.mjs";
35
37
  import { flagModeError, isEffectivelyEmpty, modeFor } from "./target.mjs";
36
38
  import {
37
- INSTALL_COMMANDS,
39
+ SUPPORTED_PACKAGE_MANAGERS,
38
40
  initGitRepo,
39
41
  installDependencies,
40
42
  isGitAvailable,
@@ -45,6 +47,15 @@ const colorFrameworkNames = Object.values(FRAMEWORKS)
45
47
  .filter((fw) => fw.scaffold.supportsColor)
46
48
  .map((fw) => fw.name);
47
49
 
50
+ const aliasText = [
51
+ ...Object.entries(FRAMEWORK_ALIASES.scaffold).map(
52
+ ([alias, id]) => `${alias} = ${id} (scaffold)`,
53
+ ),
54
+ ...Object.entries(FRAMEWORK_ALIASES.wire).map(
55
+ ([alias, id]) => `${alias} = ${id} (wire)`,
56
+ ),
57
+ ].join(", ");
58
+
48
59
  const HELP_TEXT = `Usage: create-graphql-markdown-docs [dir] [options]
49
60
 
50
61
  An empty or missing folder creates a new project (scaffold); a folder with
@@ -55,9 +66,11 @@ Shared:
55
66
  --new | --existing Force scaffold or wire mode (default: picked from the folder)
56
67
  --framework <name> Scaffold: ${Object.keys(FRAMEWORKS).join(" | ")} (default: ${DEFAULT_FRAMEWORK})
57
68
  Wire: ${Object.keys(WIRE_FRAMEWORKS).join(" | ")}
69
+ Aliases: ${aliasText}
58
70
  --schema <source> Schema source: <path|url|git:|github:>
59
71
  --pm <name> Package manager: npm | pnpm | yarn | bun
60
72
  --install / --no-install Install dependencies (or skip it)
73
+ --no-telemetry Do not send anonymous usage telemetry
61
74
  -y, --yes Accept defaults and skip all prompts
62
75
  -h, --help Show this help
63
76
  -v, --version Show the version
@@ -73,7 +86,7 @@ Wire only:
73
86
  --output <folder> Folder for the generated docs, relative to the project
74
87
  --link-root <route> Route prefix used in generated links
75
88
  --site-base <route> Base path the site is served from
76
- --script <name> package.json script to add (default: docs:api)
89
+ --script <name> package.json script to add (default: gqlmd)
77
90
  --dry-run Show what would be written without writing it
78
91
  `;
79
92
 
@@ -108,6 +121,7 @@ export function parseCliArgs(argv) {
108
121
  script: { type: "string" },
109
122
  "dry-run": { type: "boolean" },
110
123
  "no-git": { type: "boolean" },
124
+ "no-telemetry": { type: "boolean" },
111
125
  yes: { type: "boolean", short: "y" },
112
126
  help: { type: "boolean", short: "h" },
113
127
  version: { type: "boolean", short: "v" },
@@ -128,15 +142,17 @@ export function parseCliArgs(argv) {
128
142
 
129
143
  /** Fails on an unsupported --pm value. */
130
144
  function validatePackageManager(args) {
131
- if (args.pm && !Object.hasOwn(INSTALL_COMMANDS, args.pm)) {
145
+ if (args.pm && !SUPPORTED_PACKAGE_MANAGERS.includes(args.pm)) {
132
146
  fail(
133
- `Invalid --pm "${args.pm}" — expected one of: ${Object.keys(INSTALL_COMMANDS).join(", ")}.`,
147
+ `Invalid --pm "${args.pm}" — expected one of: ${SUPPORTED_PACKAGE_MANAGERS.join(", ")}.`,
134
148
  );
135
149
  }
136
150
  }
137
151
 
138
152
  async function resolveFramework(args) {
139
153
  if (args.framework) {
154
+ const aliases = FRAMEWORK_ALIASES.scaffold;
155
+ if (Object.hasOwn(aliases, args.framework)) return aliases[args.framework];
140
156
  if (
141
157
  !Object.hasOwn(FRAMEWORKS, args.framework) &&
142
158
  Object.hasOwn(WIRE_FRAMEWORKS, args.framework)
@@ -380,6 +396,13 @@ function initialColor(args, fw) {
380
396
  return color;
381
397
  }
382
398
 
399
+ /** Whether the template has nothing to customize (no title, no color). */
400
+ export function hasNoCustomization(fw) {
401
+ return (
402
+ fw.scaffold.supportsTitle === false && fw.scaffold.supportsColor === false
403
+ );
404
+ }
405
+
383
406
  /** Whether the user wants to customize title/color interactively. */
384
407
  async function wantsCustomization(fw) {
385
408
  const answer = unlessCancelled(
@@ -395,6 +418,12 @@ async function wantsCustomization(fw) {
395
418
 
396
419
  /** Optional title and color customization. */
397
420
  async function promptCustomization(args, fw) {
421
+ if (hasNoCustomization(fw)) {
422
+ if (args.title) {
423
+ prompts.log.warn(`--title does not apply to ${fw.name} — ignoring it.`);
424
+ }
425
+ return { title: "", color: initialColor(args, fw) };
426
+ }
398
427
  let title = args.title ?? "";
399
428
  let color = initialColor(args, fw);
400
429
  if (args.yes || !(await wantsCustomization(fw))) {
@@ -468,7 +497,8 @@ const SCAFFOLD_STEPS = [
468
497
  {
469
498
  id: "createProject",
470
499
  title: "Create project",
471
- run(ctx) {
500
+ async run(ctx) {
501
+ await reportTelemetry(ctx);
472
502
  applyTemplate(ctx.tempDir, ctx);
473
503
  moveIntoPlace(ctx.tempDir, ctx.projectDir);
474
504
  prompts.log.success("Project created successfully!");
@@ -52,7 +52,7 @@ export const docusaurus = {
52
52
  contentRoute: "/docs",
53
53
  outputHint: "Docusaurus reads content from docs/",
54
54
  nextSteps: ({ outputDir }) =>
55
- `Add the API docs to a sidebar (e.g. autogenerated from \`${outputDir}\`), or use the @graphql-markdown/docusaurus plugin — add it to \`plugins\` in docusaurus.config.*, it reads the same .graphqlrc.`,
55
+ `Add the API docs to a sidebar (e.g. autogenerated from \`${outputDir}\`).`,
56
56
  scaffold: {
57
57
  runScripts: ["doc", "start"],
58
58
  copyExcludes: [],
@@ -1,4 +1,5 @@
1
1
  import { docusaurus } from "./docusaurus.mjs";
2
+ import { markdown, mdx } from "./markdown.mjs";
2
3
  import { nuxt } from "./nuxt.mjs";
3
4
  import {
4
5
  docfx,
@@ -30,10 +31,11 @@ import {
30
31
  */
31
32
 
32
33
  /**
33
- * Supported scaffold targets; each key maps to `templates/<framework>`.
34
+ * Supported scaffold targets; each key maps to `templates/<framework>`, unless
35
+ * `scaffold.template` overrides it (mdx uses the markdown template).
34
36
  * `scaffold.runScripts` are the package scripts to run after install, in order.
35
37
  */
36
- export const FRAMEWORKS = { nuxt, docusaurus };
38
+ export const FRAMEWORKS = { nuxt, docusaurus, markdown, mdx };
37
39
 
38
40
  /** Every framework descriptor available in wire mode, keyed by id. */
39
41
  export const WIRE_FRAMEWORKS = {
@@ -47,7 +49,18 @@ export const WIRE_FRAMEWORKS = {
47
49
  docfx,
48
50
  mdbook,
49
51
  nuxt,
52
+ mdx,
50
53
  generic,
51
54
  };
52
55
 
56
+ /**
57
+ * Accepted `--framework` aliases per mode: alias -> framework id in that mode.
58
+ * Scaffolding has no "generic" template (plain Markdown is its equivalent);
59
+ * wiring has no "markdown" target (generic is its equivalent).
60
+ */
61
+ export const FRAMEWORK_ALIASES = {
62
+ scaffold: { generic: "markdown" },
63
+ wire: { markdown: "generic" },
64
+ };
65
+
53
66
  export const DEFAULT_FRAMEWORK = "nuxt";
@@ -0,0 +1,75 @@
1
+ import fs from "node:fs";
2
+ import path from "node:path";
3
+
4
+ import { writeGraphqlrc } from "../rewrites/graphqlrc.mjs";
5
+ import { findIndentedLine } from "../rewrites/lines.mjs";
6
+
7
+ const MDX_FORMATTER = "@graphql-markdown/formatters/mdx";
8
+ // Must match the @graphql-markdown/formatters release that ships `./mdx`.
9
+ const FORMATTERS_RANGE = "^1.2.0";
10
+
11
+ /** Adds the mdx formatter to .graphqlrc, right before the `loaders:` line. */
12
+ export function writeMdxFormatter(tempDir) {
13
+ const graphqlrcPath = path.join(tempDir, ".graphqlrc");
14
+ const content = fs.readFileSync(graphqlrcPath, "utf-8");
15
+ const found = findIndentedLine(content, "loaders:");
16
+ if (!found) {
17
+ throw new Error(
18
+ `Expected to find "loaders:" in ${graphqlrcPath}, but nothing matched — the template may have changed. Update the CLI's rewrite logic.`,
19
+ );
20
+ }
21
+ const { line, indent } = found;
22
+ fs.writeFileSync(
23
+ graphqlrcPath,
24
+ content.replace(
25
+ line,
26
+ () => `${indent}formatter: '${MDX_FORMATTER}'\n${line}`,
27
+ ),
28
+ );
29
+
30
+ const pkgPath = path.join(tempDir, "package.json");
31
+ const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
32
+ pkg.dependencies["@graphql-markdown/formatters"] = FORMATTERS_RANGE;
33
+ fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
34
+ }
35
+
36
+ const nextSteps = ({ outputDir }) =>
37
+ `Point your site navigation at \`${outputDir}\`. Manual wiring guide: https://graphql-markdown.dev`;
38
+
39
+ /** Plain Markdown scaffold descriptor (templates/markdown). */
40
+ export const markdown = {
41
+ id: "markdown",
42
+ name: "Markdown",
43
+ label: "Markdown (plain .md files)",
44
+ hint: "No site — just Markdown files in docs/",
45
+ scaffold: {
46
+ template: "markdown",
47
+ runScripts: ["doc"],
48
+ copyExcludes: [],
49
+ supportsColor: false,
50
+ supportsTitle: false,
51
+ apply(tempDir, { schemaRef, loader }) {
52
+ writeGraphqlrc(tempDir, schemaRef, loader);
53
+ },
54
+ },
55
+ };
56
+
57
+ /** Plain MDX scaffold and wire descriptor (templates/markdown + mdx formatter). */
58
+ export const mdx = {
59
+ ...markdown,
60
+ id: "mdx",
61
+ name: "MDX",
62
+ label: "MDX (plain .mdx files)",
63
+ hint: "Framework-neutral .mdx pages (plain HTML, no components)",
64
+ formatter: MDX_FORMATTER,
65
+ links: "relative",
66
+ contentRoot: "docs",
67
+ nextSteps,
68
+ scaffold: {
69
+ ...markdown.scaffold,
70
+ apply(tempDir, { schemaRef, loader }) {
71
+ writeGraphqlrc(tempDir, schemaRef, loader);
72
+ writeMdxFormatter(tempDir);
73
+ },
74
+ },
75
+ };
package/lib/helpers.mjs CHANGED
@@ -7,7 +7,7 @@ import {
7
7
  } from "package-manager-detector";
8
8
 
9
9
  import { isRemoteSchemaSource } from "./schema.mjs";
10
- import { INSTALL_COMMANDS } from "./tasks.mjs";
10
+ import { SUPPORTED_PACKAGE_MANAGERS } from "./tasks.mjs";
11
11
 
12
12
  export const DOCS_URL = "https://graphql-markdown.dev";
13
13
 
@@ -62,10 +62,10 @@ export function validateSchemaSource(value) {
62
62
  export async function resolvePackageManager(args, cwd = process.cwd()) {
63
63
  if (args.pm) return args.pm;
64
64
  // Set when launched via `<pm> create`, so it reflects what the user ran.
65
- const agent = getUserAgent()?.split("/")[0];
66
- if (agent && Object.hasOwn(INSTALL_COMMANDS, agent)) return agent;
65
+ const agent = getUserAgent();
66
+ if (agent && SUPPORTED_PACKAGE_MANAGERS.includes(agent)) return agent;
67
67
  const detected = await detectPackageManager({ cwd });
68
- if (detected?.name && Object.hasOwn(INSTALL_COMMANDS, detected.name)) {
68
+ if (detected?.name && SUPPORTED_PACKAGE_MANAGERS.includes(detected.name)) {
69
69
  return detected.name;
70
70
  }
71
71
  if (args.yes) return "npm";
package/lib/project.mjs CHANGED
@@ -99,10 +99,11 @@ export function applyTemplate(tempDir, ctx) {
99
99
  const { framework, projectDir, schemaPath, loader, title, color } = ctx;
100
100
  const fw = FRAMEWORKS[framework];
101
101
 
102
- copyDirRecursive(path.join(templatesRoot, framework), tempDir, [
103
- /^node_modules$/,
104
- ...fw.scaffold.copyExcludes,
105
- ]);
102
+ copyDirRecursive(
103
+ path.join(templatesRoot, fw.scaffold.template ?? framework),
104
+ tempDir,
105
+ [/^node_modules$/, ...fw.scaffold.copyExcludes],
106
+ );
106
107
 
107
108
  // npm strips `.gitignore` from published tarballs, so templates ship it as
108
109
  // `gitignore` and it is renamed back here.
package/lib/tasks.mjs CHANGED
@@ -1,36 +1,29 @@
1
1
  import { spawn } from "node:child_process";
2
2
 
3
3
  import * as prompts from "@clack/prompts";
4
+ import { resolveCommand } from "package-manager-detector/commands";
4
5
 
5
6
  /**
6
- * Maps each package manager to its install command and arguments.
7
- * Each entry is [command, args] to be passed to spawn().
7
+ * Package managers supported by the scaffolder.
8
8
  */
9
- export const INSTALL_COMMANDS = {
10
- npm: ["npm", ["install"]],
11
- pnpm: ["pnpm", ["install"]],
12
- yarn: ["yarn", []],
13
- bun: ["bun", ["install"]],
14
- };
9
+ export const SUPPORTED_PACKAGE_MANAGERS = ["npm", "pnpm", "yarn", "bun"];
15
10
 
16
- /**
17
- * Maps each package manager to the command that adds dev dependencies.
18
- * Each entry is [command, args]; the packages are appended to args.
19
- */
20
- const ADD_DEV_COMMANDS = {
21
- npm: ["npm", ["install", "--save-dev"]],
22
- pnpm: ["pnpm", ["add", "--save-dev"]],
23
- yarn: ["yarn", ["add", "--dev"]],
24
- bun: ["bun", ["add", "--dev"]],
25
- };
11
+ function resolveOrNpm(packageManager, intent, args) {
12
+ const agent = SUPPORTED_PACKAGE_MANAGERS.includes(packageManager)
13
+ ? packageManager
14
+ : "npm";
15
+ const resolved = resolveCommand(agent, intent, args);
16
+ if (!resolved) {
17
+ throw new Error(`Unsupported ${intent} command for ${agent}`);
18
+ }
19
+ return [resolved.command, resolved.args];
20
+ }
26
21
 
27
22
  function addDevArgs(packageManager, packages, { workspaceRoot = false } = {}) {
28
- const [command, args] =
29
- ADD_DEV_COMMANDS[packageManager] ?? ADD_DEV_COMMANDS.npm;
30
23
  const rootFlag = workspaceRoot
31
24
  ? ({ pnpm: ["-w"], yarn: ["-W"] }[packageManager] ?? [])
32
25
  : [];
33
- return [command, [...args, ...rootFlag, ...packages]];
26
+ return resolveOrNpm(packageManager, "add", ["-D", ...rootFlag, ...packages]);
34
27
  }
35
28
 
36
29
  /**
@@ -73,14 +66,13 @@ export async function isGitAvailable() {
73
66
  */
74
67
  export async function installDependencies(packageManager, projectDir) {
75
68
  prompts.log.info(`Installing dependencies with ${packageManager}...`);
76
- const [command, args] =
77
- INSTALL_COMMANDS[packageManager] ?? INSTALL_COMMANDS.npm;
69
+ const [command, args] = resolveOrNpm(packageManager, "install", []);
78
70
  await runCommand(command, args, { cwd: projectDir });
79
71
  prompts.log.success("Dependencies installed!");
80
72
  }
81
73
 
82
74
  /**
83
- * Command line that adds packages as dev dependencies, e.g. "bun add --dev a b".
75
+ * Command line that adds packages as dev dependencies, e.g. "bun add -D a b".
84
76
  * @param {string} packageManager
85
77
  * @param {string[]} packages
86
78
  * @returns {string}
@@ -0,0 +1,46 @@
1
+ import fs from "node:fs";
2
+ import path from "node:path";
3
+
4
+ import { note } from "@clack/prompts";
5
+ import { track } from "@graphql-markdown/telemetry";
6
+
7
+ import { packageRoot } from "./project.mjs";
8
+ import { EXAMPLE_SCHEMA_REF } from "./schema.mjs";
9
+
10
+ const PKG_NAME = "create-graphql-markdown-docs";
11
+
12
+ /** The prompt answers worth reporting; the telemetry package masks custom values. */
13
+ function configFor(ctx) {
14
+ if (ctx.mode === "wire") {
15
+ return { schema: ctx.schemaRef, linkRoot: ctx.linkRoot };
16
+ }
17
+ return { schema: ctx.schemaPath ?? EXAMPLE_SCHEMA_REF };
18
+ }
19
+
20
+ /**
21
+ * Reports one anonymous create event (`create_scaffold` or `create_wire`).
22
+ * Never throws: telemetry must not affect a run. The full notice is shown
23
+ * as a clack note written to stderr, so stdout stays clean. Nothing is sent on `--dry-run`.
24
+ */
25
+ export async function reportTelemetry(ctx) {
26
+ if (ctx.args?.["dry-run"]) return;
27
+ try {
28
+ const { version } = JSON.parse(
29
+ fs.readFileSync(path.join(packageRoot, "package.json"), "utf-8"),
30
+ );
31
+ await track({
32
+ event: ctx.mode === "wire" ? "create_wire" : "create_scaffold",
33
+ trigger: "create",
34
+ pkg: PKG_NAME,
35
+ pkgVersion: version,
36
+ target: ctx.framework,
37
+ mode: ctx.mode,
38
+ config: configFor(ctx),
39
+ option: ctx.args["no-telemetry"] ? false : undefined,
40
+ onFullNotice: (notice) =>
41
+ note(notice, "Telemetry", { output: process.stderr }),
42
+ });
43
+ } catch {
44
+ // telemetry must never affect a run
45
+ }
46
+ }
package/lib/wire/plan.mjs CHANGED
@@ -36,7 +36,7 @@ const GRAPHQL_CONFIG_FILES = [
36
36
  /**
37
37
  * Inspect a project directory for package.json and an existing GraphQL config.
38
38
  * @param {string} projectDir
39
- * @returns {{ packageJson: object | null, packageJsonIndent: string | number, existingConfig: string | null }}
39
+ * @returns {{ packageJson: object | null, packageJsonIndent: string | number, existingConfig: string | null, workspaceRoot: boolean, pnpmWorkspace: boolean, yarnBerry: boolean }}
40
40
  */
41
41
  export function inspectProject(projectDir) {
42
42
  let packageJson = null;
@@ -56,10 +56,21 @@ export function inspectProject(projectDir) {
56
56
  if (!existingConfig && packageJson && "graphql" in packageJson) {
57
57
  existingConfig = "package.json#graphql";
58
58
  }
59
+ const pnpmWorkspace = fs.existsSync(
60
+ path.join(projectDir, "pnpm-workspace.yaml"),
61
+ );
62
+ const workspaceRoot =
63
+ Boolean(packageJson && "workspaces" in packageJson) || pnpmWorkspace;
64
+ const yarnBerry =
65
+ fs.existsSync(path.join(projectDir, ".yarnrc.yml")) ||
66
+ /^yarn@(?:[2-9]|\d{2,})\./.test(packageJson?.packageManager ?? "");
59
67
  return {
60
68
  packageJson,
61
69
  packageJsonIndent,
62
70
  existingConfig: existingConfig ?? null,
71
+ workspaceRoot,
72
+ pnpmWorkspace,
73
+ yarnBerry,
63
74
  };
64
75
  }
65
76
 
@@ -155,6 +166,9 @@ export function buildGraphqlrc({
155
166
  };
156
167
  }
157
168
 
169
+ /** Default package.json script added in wire mode; namespaced to avoid clashes. */
170
+ export const DEFAULT_SCRIPT_NAME = "gqlmd";
171
+
158
172
  /**
159
173
  * Plan the files and package.json changes needed to wire a project.
160
174
  * @param {object} inputs Arguments for buildGraphqlrc.
@@ -162,7 +176,11 @@ export function buildGraphqlrc({
162
176
  * @param {{ scriptName?: string }} [options]
163
177
  * @returns {{ files: { path: string, content: string }[], mergeBlock?: string, script: object, warnings: string[] }}
164
178
  */
165
- export function planWire(inputs, project, { scriptName = "docs:api" } = {}) {
179
+ export function planWire(
180
+ inputs,
181
+ project,
182
+ { scriptName = DEFAULT_SCRIPT_NAME } = {},
183
+ ) {
166
184
  const config = buildGraphqlrc(inputs);
167
185
  const warnings = [];
168
186
  let files = [];
@@ -4,7 +4,7 @@ import path from "node:path";
4
4
 
5
5
  import * as prompts from "@clack/prompts";
6
6
 
7
- import { WIRE_FRAMEWORKS } from "../frameworks/index.mjs";
7
+ import { FRAMEWORK_ALIASES, WIRE_FRAMEWORKS } from "../frameworks/index.mjs";
8
8
  import { normalizeOutput, suggestLinkRoot } from "../frameworks/links.mjs";
9
9
  import {
10
10
  DOCS_URL,
@@ -14,12 +14,14 @@ import {
14
14
  unlessCancelled,
15
15
  validateSchemaSource,
16
16
  } from "../helpers.mjs";
17
+ import { reportTelemetry } from "../telemetry.mjs";
17
18
  import { detectLoader } from "../schema.mjs";
18
19
  import { addDevCommand, addDevDependencies } from "../tasks.mjs";
19
20
  import { detectFrameworks, toSchemaRef } from "../target.mjs";
20
21
  import { requiredPackages } from "./deps.mjs";
21
22
  import {
22
23
  applyWirePlan,
24
+ DEFAULT_SCRIPT_NAME,
23
25
  formatWirePlan,
24
26
  inspectProject,
25
27
  planWire,
@@ -70,6 +72,8 @@ async function resolveWireFramework(ctx) {
70
72
  const { args, detected } = ctx;
71
73
  const requested = requestedFramework(args);
72
74
  if (requested) {
75
+ const aliases = FRAMEWORK_ALIASES.wire;
76
+ if (Object.hasOwn(aliases, requested)) return aliases[requested];
73
77
  if (!Object.hasOwn(WIRE_FRAMEWORKS, requested)) {
74
78
  fail(
75
79
  `Invalid --framework "${requested}" — expected one of: ${Object.keys(WIRE_FRAMEWORKS).join(", ")}.`,
@@ -205,7 +209,8 @@ function planDependencies(ctx) {
205
209
  }
206
210
  }
207
211
 
208
- function writePlan(ctx) {
212
+ async function writePlan(ctx) {
213
+ await reportTelemetry(ctx);
209
214
  const { args, projectDir, project, descriptor } = ctx;
210
215
  const plan = planWire(
211
216
  {
@@ -244,7 +249,7 @@ export const WIRE_STEPS = [
244
249
  run(ctx) {
245
250
  ctx.project = inspectProject(ctx.projectDir);
246
251
  ctx.detected = detectFrameworks(ctx.project.packageJson);
247
- ctx.scriptName = ctx.args.script || "docs:api";
252
+ ctx.scriptName = ctx.args.script || DEFAULT_SCRIPT_NAME;
248
253
  preflight(ctx);
249
254
  },
250
255
  },
@@ -280,19 +285,40 @@ export const WIRE_STEPS = [
280
285
  when: (ctx) =>
281
286
  Boolean(ctx.args.install) && !ctx.args["dry-run"] && needsInstall(ctx),
282
287
  run: (ctx) =>
283
- addDevDependencies(ctx.packageManager, ctx.projectDir, ctx.packages),
288
+ addDevDependencies(
289
+ ctx.packageManager,
290
+ ctx.projectDir,
291
+ ctx.packages,
292
+ addDevOptions(ctx),
293
+ ),
284
294
  catchUp: (ctx) =>
285
295
  needsInstall(ctx)
286
- ? [addDevCommand(ctx.packageManager, ctx.packages)]
296
+ ? [addDevCommand(ctx.packageManager, ctx.packages, addDevOptions(ctx))]
287
297
  : [],
288
298
  },
289
299
  ];
290
300
 
301
+ /** Options for adding dev deps; yarn berry has no -W workspace-root flag. */
302
+ function addDevOptions(ctx) {
303
+ const { project, packageManager } = ctx;
304
+ const workspaceRoot =
305
+ packageManager === "pnpm"
306
+ ? Boolean(project.pnpmWorkspace)
307
+ : packageManager === "yarn"
308
+ ? Boolean(project.packageJson?.workspaces) && !project.yarnBerry
309
+ : false;
310
+ return { workspaceRoot };
311
+ }
312
+
291
313
  /** Prints the closing summary for wire mode; `outcomes` are the step results. */
292
314
  export function printWireOutro(ctx, outcomes = []) {
293
315
  if (ctx.args["dry-run"]) {
294
316
  if (needsInstall(ctx)) {
295
- const command = addDevCommand(ctx.packageManager, ctx.packages);
317
+ const command = addDevCommand(
318
+ ctx.packageManager,
319
+ ctx.packages,
320
+ addDevOptions(ctx),
321
+ );
296
322
  prompts.log.info(
297
323
  ctx.args.install
298
324
  ? `Would install: ${command}`
@@ -306,7 +332,7 @@ export function printWireOutro(ctx, outcomes = []) {
306
332
  const hasScript = plan.script.name || plan.script.skipped?.includes("exists");
307
333
  const generate = hasScript
308
334
  ? `${ctx.packageManager} run ${scriptName}`
309
- : "npx -p @graphql-markdown/cli gqlmd graphql-to-doc";
335
+ : "npx -p @graphql-markdown/cli@latest gqlmd graphql-to-doc";
310
336
  // Commands for steps that did not finish (e.g. the install), then the generate step.
311
337
  const catchUp = outcomes
312
338
  .filter((outcome) => outcome.status !== "done" && outcome.catchUp)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "create-graphql-markdown-docs",
3
- "version": "1.0.0",
3
+ "version": "1.1.0",
4
4
  "description": "Create a new GraphQL API documentation site with GraphQL Markdown and Nuxt or Docusaurus",
5
5
  "type": "module",
6
6
  "homepage": "https://graphql-markdown.dev",
@@ -47,8 +47,9 @@
47
47
  ],
48
48
  "dependencies": {
49
49
  "@clack/prompts": "^1.0.0",
50
- "graphql": "^16.8.0",
51
- "package-manager-detector": "^1.0.0"
50
+ "@graphql-markdown/telemetry": "^0.1.0",
51
+ "graphql": "^16.8.0 || ^17.0.0",
52
+ "package-manager-detector": "^1.8.0"
52
53
  },
53
54
  "devDependencies": {
54
55
  "@graphql-markdown/tooling-config": "^1.0.0"
@@ -15,7 +15,7 @@
15
15
  "dependencies": {
16
16
  "@docusaurus/core": "^3.10.0",
17
17
  "@docusaurus/preset-classic": "^3.10.0",
18
- "@graphql-markdown/docusaurus": "^1.38.1",
18
+ "@graphql-markdown/docusaurus": "^1.39.0",
19
19
  "@graphql-tools/graphql-file-loader": "^8.0.0",
20
20
  "@mdx-js/react": "^3.1.1",
21
21
  "graphql": "^16.13.2",
@@ -0,0 +1,9 @@
1
+ schema: './schema/example.graphql'
2
+ extensions:
3
+ graphql-markdown:
4
+ rootPath: './docs'
5
+ baseURL: '.'
6
+ loaders:
7
+ GraphQLFileLoader: '@graphql-tools/graphql-file-loader'
8
+ printTypeOptions:
9
+ deprecated: 'group'
@@ -0,0 +1,13 @@
1
+ # GraphQL-Markdown docs
2
+
3
+ API documentation generated with [GraphQL-Markdown](https://graphql-markdown.dev). The pages are plain files written to `docs/` (`.md`, or `.mdx` for the MDX variant), with no site framework attached.
4
+
5
+ ## Generate
6
+
7
+ ```shell
8
+ npm run doc
9
+ ```
10
+
11
+ ### Your GraphQL Schema
12
+
13
+ The schema is configured in `.graphqlrc` (see the [documentation](https://graphql-markdown.dev/docs/configuration#graphql-config)). By default it reads the bundled `schema/example.graphql`. To change it, edit `schema` in `.graphqlrc` (a local file, or a URL, `git:` or `github:` reference) and declare the matching [graphql-tools loader](https://github.com/ardatan/graphql-tools/tree/master/packages/loaders) under `loaders`. Then run `npm run doc` again.
File without changes
@@ -0,0 +1 @@
1
+ node_modules/
@@ -0,0 +1,13 @@
1
+ {
2
+ "name": "graphql-markdown-docs",
3
+ "private": true,
4
+ "scripts": {
5
+ "doc": "gqlmd graphql-to-doc"
6
+ },
7
+ "dependencies": {
8
+ "@graphql-markdown/cli": "^1.2.0",
9
+ "@graphql-tools/graphql-file-loader": "^8.0.0",
10
+ "graphql": "^16.13.2",
11
+ "graphql-config": "^5.1.6"
12
+ }
13
+ }
@@ -0,0 +1,55 @@
1
+ """
2
+ A simple example GraphQL schema demonstrating the GraphQL Markdown theme.
3
+ """
4
+ scalar DateTime
5
+
6
+ """
7
+ The root query type for the API.
8
+ """
9
+ type Query {
10
+ """
11
+ Retrieve a user by their ID.
12
+ """
13
+ user(id: ID!): User
14
+
15
+ """
16
+ List all available users.
17
+ """
18
+ users: [User!]!
19
+ }
20
+
21
+ """
22
+ A user in the system.
23
+ """
24
+ type User {
25
+ """
26
+ The unique identifier for this user.
27
+ """
28
+ id: ID!
29
+
30
+ """
31
+ The user's name.
32
+ """
33
+ name: String!
34
+
35
+ """
36
+ The user's email address.
37
+ """
38
+ email: String!
39
+
40
+ """
41
+ When this user account was created.
42
+ """
43
+ createdAt: DateTime!
44
+
45
+ """
46
+ The user's profile picture URL.
47
+ @deprecated Use `avatar` instead.
48
+ """
49
+ profilePictureUrl: String @deprecated(reason: "Use avatar field instead")
50
+
51
+ """
52
+ The user's avatar profile picture.
53
+ """
54
+ avatar: String
55
+ }
@@ -11,11 +11,11 @@
11
11
  "preview": "nuxi preview"
12
12
  },
13
13
  "dependencies": {
14
- "@graphql-markdown/nuxt-theme": "^0.1.3",
14
+ "@graphql-markdown/nuxt-theme": "^0.2.0",
15
15
  "@nuxt/content": "^3.16.0",
16
16
  "@nuxt/ui": "^4.11.0",
17
17
  "better-sqlite3": "^13.0.3",
18
- "nuxt": "^4.5.2",
18
+ "nuxt": "^4.6.0",
19
19
  "tailwindcss": "^4.3.3"
20
20
  },
21
21
  "devDependencies": {},