{"id":16847132,"url":"https://github.com/lunaticmuch/nextjs-graphql-schema-docs","last_synced_at":"2026-04-18T06:02:08.566Z","repository":{"id":170711223,"uuid":"626606390","full_name":"LunaticMuch/nextjs-graphql-schema-docs","owner":"LunaticMuch","description":"A plugin for generating documentation of a GraphQL schema within a Next.JS website","archived":false,"fork":false,"pushed_at":"2023-06-08T09:17:27.000Z","size":767,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-10-06T11:19:49.753Z","etag":null,"topics":["documentation","graphql","knowledge","nextjs","react"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/nextjs-graphql-schema-docs","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/LunaticMuch.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-04-11T20:04:44.000Z","updated_at":"2024-10-01T16:02:26.000Z","dependencies_parsed_at":"2023-07-06T14:15:46.946Z","dependency_job_id":null,"html_url":"https://github.com/LunaticMuch/nextjs-graphql-schema-docs","commit_stats":null,"previous_names":["lunaticmuch/nextjs-graphql-schema-docs"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/LunaticMuch/nextjs-graphql-schema-docs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LunaticMuch%2Fnextjs-graphql-schema-docs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LunaticMuch%2Fnextjs-graphql-schema-docs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LunaticMuch%2Fnextjs-graphql-schema-docs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LunaticMuch%2Fnextjs-graphql-schema-docs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LunaticMuch","download_url":"https://codeload.github.com/LunaticMuch/nextjs-graphql-schema-docs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LunaticMuch%2Fnextjs-graphql-schema-docs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31958467,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T00:39:45.007Z","status":"online","status_checked_at":"2026-04-18T02:00:07.018Z","response_time":103,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["documentation","graphql","knowledge","nextjs","react"],"created_at":"2024-10-13T13:06:43.790Z","updated_at":"2026-04-18T06:02:08.505Z","avatar_url":"https://github.com/LunaticMuch.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Plugin for generating schema documentation in Next.JS\n\n\u003e **WARNING**: Be careful, this is currently a **beta**, or a preview-release version. It might work as expected or not, it might even not work at all, or I might sell your house without your knowledge!\n\n## Rationale\n\n### Why\n\nGraphQL Schema includes documentation in the schema definition. This is fantastic. However, browsing the documentation is often, if not always, limited to GraphQL Playgrounds. Playgrounds offer documentation browsing only for the purpose of building a query. More than showing documentation, the playground delivers documentation as handy reference for an a software developer. In my opinion, that could be much better. Something I love is [GraphQL API schema documentation](https://shopify.dev/docs/api/admin-graphql) from [Shopify](https://shopify.com). This documentation, which is derived from the schema, with some additions done outside it (it is a guess, the the method and solution are not open or disclosed), is the way to go in my opinion. I makes easier to browse the entire schema, particularly for those who are not software engineers building a query, and it allows you to integrate the reference into your application manual or playbook.\n\n### How\n\nIn theory, and even in practice, GraphQL allows for introspection. So it is quite easy to read the schema and work with it. Otherwise, if you have access to the schema SDL that is quite easy.\nHaving access to the schema is the first part, and the simplest one. In GraphQL, given it is a _type system_ everything is a type, so if requires some logic for getting it in a way it can be easily printed.\n\n### Alternatives\n\nThe list of alternatives is quite short, if not narrow and limited to one. The only alterative I have found so far is [GraphQL Markdown](https://graphql-markdown.github.io). This plugin, built for [docusaurus](https://docusaurus.io), boosts the same concept I am trying to deliver. However, it's limited to markdown. Markdown is not, IMO, fit for purpose. The reason is that Markdown is perfect when it comes to writing text documents, with no formal structure. It fails short if you want to render a richer user interface. If you see the output of this plugin, despite the very good job, is not the best and can even confuse the reader. MDX is an option, actually not available in this plugin. Anyway, it would work correctly only with docusaurus and still limited to how docusaurus works.\n\n## Usage\n\n\u003e **NOTE**: It is assumed you have a basic knowledge of [Next.JS router](https://nextjs.org/docs/app/building-your-application/routing) and, in particular, [dynamic routes](https://nextjs.org/docs/app/building-your-application/routing/dynamic-routes).\n\n### `schemaParser` class\n\nThe root of the component is a class. The class has been used to facilitate the ingestion and parsing of the schema. You might want, in the page you use for the dynamic route, to create an instance of `schemaParser`.\n\n```javascript\nconst t = new schemaParser(\"schema.graphql\");\n```\n\n### Dynamic router\n\nYou need a catch-all route for using this plugin. The route should be `[...type]`\n\nYou can either use the pages router with `getStaticPaths` or the new app router with `getStaticParams`. This is an example with the pages router:\n\n```javascript\nexport async function getStaticPaths() {\n\tconst routes = t.getRoutes();\n\treturn {\n\t\tpaths: routes,\n\t\tfallback: false,\n\t};\n}\n```\n\n### Printing data\n\n## API Reference\n\nThis package exports a class named `schemaParser`\n\n### `schemaParser(uri: string)`\n\nThe API access a URI as a `string` which can be one of the following:\n\n- A remote GraphQL introspection endpoint, in the format `https://somedomain.sometld/any/path/if/needed`. Only `https://` is accepted as valid URL.\n- A schema SDL file, either a single file or glob. The schema must be valid, no partial schema are supported.\n\nThe load of schema is backed by [@graphql-tools](https://the-guild.dev/graphql/tools/docs/schema-loading#load-graphqlschema-by-using-different-loaders-from-different-sources)\n\n### `schemaParser.getRoutes()`\n\nReturn a list of routes in a [catch-all format](https://nextjs.org/docs/app/building-your-application/routing/dynamic-routes#catch-all-segments).\nExample:\n\n```javascript\n[\n\t{ params: { type: \"Author\" } },\n\t{ params: { type: \"Book\" } },\n\t{ params: { type: \"Name\" } },\n];\n```\n\n### `schemaParser.getTypename(kind: string, name: string)`\n\nReturn the type information for a given type.\nThe kind being accepted is the same as part of the route definition.\n\nIt can be destructed in this way\n\n```javascript\nconst [kind, type] = context.params.type;\n```\n\n### `schemaParser.getSidebar(prefix: string)`\n\nReturn a displayable sidebar with all types\n\n## Using the embedded example\n\n1. Clone the repo as usual\n2. Run the following to install dependencies\n\n```bash\nnpm ci \u0026\u0026 npm ci --prefix ./example\n```\n\n3. Build the plugin and start the server\n\n```bash\nnpm run start:example\n```\n\nNow the example server will be available on [http://localhost:3000/](http://localhost:3000/)\n\nThe demo schema is available in `schema/schema.graphql`. You can add types and fields, but always add a description as right now it does not catch a missing description and throws an error.\n\n## Credits\n\nMuch of the work has been inspired from [GraphQL Markdown](https://graphql-markdown.github.io) and [GraphQL Voyager](https://github.com/graphql-kit/graphql-voyager).\nThe core code for working out the schema is extracted from GraphQL Voyager.\n\nA special thank to [@della-90](https://github.com/della-90) for the work on [parents identification](https://github.com/LunaticMuch/next-schema-plugin-ts/pull/1).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flunaticmuch%2Fnextjs-graphql-schema-docs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flunaticmuch%2Fnextjs-graphql-schema-docs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flunaticmuch%2Fnextjs-graphql-schema-docs/lists"}