A framework for delightful GraphQL developer portals ✨.
npm add polen
Have a schema.graphql GraphQL 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:3001):
node build/app.js
Experience Polen in action with our live documentation sites:
Featured examples:
Our demos are available at different stability levels, matching npm's dist tags:
Stable Release (latest): /polen/latest/pokemon
1.0.0)npm install polenPre-release (next): /polen/next/pokemon
1.1.0-beta.1)npm install polen@nextTagged Versions: Access any specific release
npm install polen@1.0.0[!TIP] The correspondence between demo URLs and npm versions makes it easy to test features before upgrading. If you're using
polen@1.0.0, visit/polen/1.0.0/pokemonto see exactly how your docs will look!
Find the source code for these demos and more in the examples directory.
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 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-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 }`,
},
],
},
},
},
})
You can add pages to your developer portal by adding markdown (.md) or MDX (.mdx) files to a
pages directory.
pages directory) file path becomes the web path.index is an index page.foo/index.md becomes
route /foo .foo/index.md and foo.md exist, then the former is used, latter
ignored, and a warning is raised.Example:
| File | Route | Navigation Bar Title |
|---|---|---|
pages/foo.md | /foo | Foo |
pages/foo.mdx | /foo | Foo |
pages/foo/index.md | /foo | Foo |
pages/foo/index.mdx | /foo | Foo |
pages/foo/bar.md | /foo/bar | Foo |
pages/foo/bar.mdx | /foo/bar | Foo |
You can control the order of pages in the sidebar by prefixing file names with numbers followed by _ or -. The numeric prefix affects only the sidebar ordering - it does not appear in the page URL or title.
<number>_<name>.md or <number>-<name>.md01_intro.md, 10_getting-started.md, 20-configuration.md10_about.md and 20_about.md), the file with the higher number is usedExample:
| File | Route | Sidebar Title | Order |
|---|---|---|---|
pages/10_getting-started.md | /getting-started | Getting Started | 1st |
pages/20_configuration.md | /configuration | Configuration | 2nd |
pages/30_advanced.md | /advanced | Advanced | 3rd |
pages/api-reference.md | /api-reference | Api Reference | 4th |
pages/troubleshooting.md | /troubleshooting | Troubleshooting | 5th |
Markdown files (.md) are supported using remark. This is the same underlying engine as MDX thus you can rely on consistent behavior between your .md and .mdx files.
Polen supports:
In the future you will be able to extend Polen in your project with additional Remark plugins. Track this feature in #64.
If you're new to Markdown, here are some great resources to get started:
Syntax features available to you include:
Via CommonMark:
Via GitHub Flavored Markdown:
MDX begins where Markdown ends. So everything stated there such as regarding supported Markdown flavours applies here too.
MDX files (.mdx) allow you to use JSX/React components within your markdown content. This enables
interactive documentation with live examples, custom components, and more.
Example MDX page:
# Interactive Documentation
import { Button } from "@radix-ui/themes";
This page demonstrates MDX features.
<Button onClick={() => alert("Hello from MDX!")}>Click me!</Button>
## Code Examples
You can mix markdown with React components for powerful documentation:
export const CodeExample = ({ language, code }) => (
<pre>
<code className={`language-${language}`}>{code}</code>
</pre>
);
<CodeExample
language="graphql"
code={`
query GetUser($id: ID!) {
user(id: $id) {
name
email
}
}
`}
/>
When you build you may choose between SSG and SSR. The default is SSG.
npx polen build --type ssg
Deploy the contents of the ./build directory on your favourite static site provider.
In the future Polen will have features that motivate using a server, but for now there is no particular benefit. Use SSG instead.
Polen supports deploying to subdirectories through the build.base configuration option. This is useful for:
/my-project/)/pr-123/)// polen.config.ts
import { Polen } from 'polen'
export default Polen.defineConfig({
build: {
base: '/my-project/', // Must start and end with /
},
})
When configured, Polen will output differently:
You can also set the base path via CLI:
npx polen build --base /my-project/
npx polen dev --base /my-project/
The CLI flag takes precedence over the config file setting.
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) // true
Polen comes with a light-weight command to instantly view any GraphQL schema.
Example:
npx polen open --name github
See docs for more details
npx polen open --help
Refer to releases on this repo.
If you are working on Polen itself, then refer to DEVELOPMENT.md for details about workflow, testing, etc.
FAQs
A framework for delightful GraphQL developer portals
The npm package polen receives a total of 370 weekly downloads. As such, polen popularity was classified as not popular.
We found that polen demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
ECMAScript 2025 introduces Iterator Helpers, Set methods, JSON modules, and more in its latest spec update approved by Ecma in June 2025.
Security News
A new Node.js homepage button linking to paid support for EOL versions has sparked a heated discussion among contributors and the wider community.
Research
North Korean threat actors linked to the Contagious Interview campaign return with 35 new malicious npm packages using a stealthy multi-stage malware loader.