A framework for delightful GraphQL developer portals ✨.
npm add polen
-
Have a
schema.graphqlGraphQL schema file in your project directory.type Query { hello: String }
-
Build your developer portal.
npx polen build
-
You now have a deployable developer portal. Try it locally (http://localhost:5174):
node dist/entry.js
You can find working examples in the examples directory.
You can provide a GraphQL schema to Polen in various ways.
Have a single schema.graphql SDL file in your project directory. Example:
schema.graphql
Have a schema directory in your project directory with multiple versions of
your schema as SDL files named using format: YYYY-MM-DD.graphql. Example:
schema/
2023-
8000
01-13.graphql
2020-09-26.graphql
This approach allows Polen to render a changelog for your schema. Refer to Changelog.
You can provide a schema to Polen in memory via configuration.
You have control to provide one or multiple schemas, with or without dates.
If no dates are given then the current time is assumed.
If you provide multiple versions then Polen can render a changelog for you. Refer to Changelog.
Basic example:
// polen.config.ts
import { Polen } from 'polen'
export default Polen.defineConfig({
schema: {
useDataSources: `memory`,
dataSources: {
memory: {
versions: [{
date: new Date('2023-01-13'),
value: `type Query { hello: String }`,
}],
},
},
},
})If you provide Polen with a schema, Polen will automatically render reference documentation for it.
If you provide multiple versions of your schema then the reference is based on the schema with the latest date.
Polen can render a changelog for your schema.
This feature is automatically enabled when you provide multiple versions of your schema. Refer to Provide a Schema for details on how to do that.
You can append/prepend/replace descriptions of types and fields in your schema.
Any Markdown syntax in your content will be automatically rendered.
import { Polen } from 'polen'
export default Polen.defineConfig({
templateVariables: {
title: `Pokemon Developer Portal`,
},
schemaAugmentations: [
{
type: `description`,
on: {
type: `TargetType`,
name: `Query`,
},
placement: `over`,
content:
`**Content from [Polen](https://github.com/the-guild-org/polen)**.`,
},
],
})You can add pages to your developer portal by adding markdown files to the
pages directory in your project root directory.
- A file becomes a page.
- The relative (to
pagesdirectory) file path becomes the web path. - Navigation Bar
- Top level pages are listed in the navigation bar.
- Index Pages
- A file named
indexis an index page. - The file name is elided in the route. For example
foo/index.mdbecomes route/foo. - Details:
- If both
foo/index.mdandfoo.mdexist, then the former is used, latter ignored, and a warning is raised.
- If both
- A file named
Example:
| File | Route | Navigation Bar Title |
|---|---|---|
pages/foo.md |
/foo |
Foo |
pages/foo/index.md |
/foo |
Foo |
pages/foo/bar.md |
/foo/bar |
Foo |
Polen is an ESM only package. If you are using CJS, then you need
NodeJS version >=22.0.0 to require it.
You can import a Polen namespace from polen. You can import its bare exports
from polen/polen.
import { Polen } from 'polen'
import { defineConfig } from 'polen/polen'
console.log(Polen.defineConfig === defineConfig) // truePolen comes with a light-weight command to instantly view any GraphQL schema.
Example:
npx polen open --name githubSee docs for more details
npx polen open --helpRefer to releases on this repo.
If you are working on Polen itself, then refer to DEVELOPMENT.md for details about workflow, testing, etc.