the-guild-org · jasonkuhrt · Apr 14, 2025 · Apr 11, 2025 · Apr 12, 2025 · Apr 12, 2025
diff --git a/.github/workflows/pr.yaml b/.github/workflows/pr.yaml
@@ -33,6 +33,20 @@ jobs:
       - uses: actions/checkout@v4
       - uses: ./.github/actions/setup
       - run: pnpm check:types
+  test-integration:
+    strategy:
+      matrix:
+        os: ['ubuntu-latest'] #, 'macos-latest', 'windows-latest'
+        node-version: [22.x]
+    runs-on: ${{matrix.os}}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./.github/actions/setup
+        with:
+          node-version: ${{matrix.node-version}}
+      - name: Install Playwright Binaries
+        uses: ./.github/actions/install-playwright-binaries
+      - run: pnpm test:integration
   test-examples:
    strategy:
       matrix:

diff --git a/.gitignore b/.gitignore
@@ -31,4 +31,5 @@ dist-ssr
 /examples/**/build
 examples/*/pnpm-workspace.yaml
 examples/_tests/__results__
+tests/*/__results__
 tsconfig.build.tsbuildinfo
diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
@@ -2,33 +2,35 @@
 
 ## Examples
 
-- We maintain fully working examples under `examples/*` (except directories
-  prefixed with `_` which are for meta purposes like testing).
-- These can help you with:
-  - Your feature development (see [Developing With](#developing-with)).
-  - Your testing of new Polen features (see [Testing](#testing)).
+- We maintain fully working examples under `examples/*`
+- Directories prefixed with `_` are for meta purposes (like testing).
+
+### Why
+
+- Functions as runnable documentation for users
+- Functions as development sandboxes for us (see
+  [Developing With](#developing-with))
+- Functions as sources for end to end tests (see [Testing](#testing))
 
 ### Developing With
 
 During local development you can link the source code with examples to try out
 changes. to the example projects by running.
 
-#### One Time System Setup
-
-1. [`pnpm link`](https://pnpm.io/cli/link) in the root directory.
+<!-- #### One Time System Setup
+TODO: Waiting on https://github.com/orgs/pnpm/discussions/9411
+1. [`pnpm link`](https://pnpm.io/cli/link) in the root directory. -->
 
 #### Session Setup
 
-1. In an example project, run `pnpm link polen`.
-2. In the root directory, run `pnpm run dev`.
-3. When you are done, revert the change to the example's `package.json` in
-   regards to the `polen` dependency having become a link.
-
-#### Notes
-
-1. `pnpm link` will result in a `pnpm-workspace.yaml` file in the example
-   project directory. These files are ignored via `.gitignore` and so will never
-   be committed.
+1. In the root directory, run `pnpm run dev` (to have TS source being emitted as
+   JS)
+2. In an example project:
+   1. Run `pnpm link ../..`
+   2. Run `pnpm run dev`
+   3. Now open the example app (http://localhost:5173)
+   4. When you are done revert changes caused by step 2.1 by running
+      `pnpm run examples:unlink`
 
 ### Testing
 

diff --git a/README.md b/README.md
@@ -5,10 +5,12 @@ A framework for delightful GraphQL developer portals ✨.
 ## Installation
 
 ```
-npm add polen vite
+npm add polen vite react-dom
 ```
 
-Vite is a peer dependency of Polen.
+- `vite` is a peer dependency of Polen.
+- `react-dom` is needed to work around an issue with `react-router`
+  ([1](https://github.com/the-guild-org/polen/pull/9#issuecomment-2801683840))
 
 ## Example
 
@@ -49,6 +51,34 @@ The following shows minimal default usage.
 
 ## Guide
 
+### Schema Augmentations
+
+#### Schema Descriptions
+
+You can append/prepend/replace descriptions of types and fields in your schema.
+
+```ts
+import { Polen } from 'polen'
+
+export default Polen.createConfiguration({
+  templateVariables: {
+    title: `Basic Developer Portal`,
+  },
+  schemaAugmentations: [
+    {
+      type: `description`,
+      on: {
+        type: `TargetType`,
+        name: `Query`,
+      },
+      placement: `over`,
+      content:
+        `**Content from [Polen](https://github.com/the-guild-org/polen)**.`,
+    },
+  ],
+})
+```
+
 ### Package
 
 #### ESM
@@ -67,3 +97,15 @@ import { VitePlugin } from 'polen/exports'
 
 console.log(Polen.VitePlugin === VitePlugin) // true
 ```
+
+## Other
+
+### Changelog
+
+Refer to
+[releases on this repo](https://github.com/the-guild-org/polen/releases).
+
+### Development
+
+If you are working on Polen itself, then refer to
+[DEVELOPMENT.md](./DEVELOPMENT.md) for details about workflow, testing, etc.
diff --git a/eslint.config.js b/eslint.config.js
@@ -1,4 +1,4 @@
-// import globals from 'globals'
+import globals from 'globals'
 import reactHooks from 'eslint-plugin-react-hooks'
 // import reactRefresh from 'eslint-plugin-react-refresh'
 import unusedImports from 'eslint-plugin-unused-imports'
@@ -21,6 +21,9 @@ export default tsEslint.config(
   reactHooks.configs['recommended-latest'],
   {
     languageOptions: {
+      globals: {
+        ...globals.browser,
+      },
       parserOptions: {
         projectService: true,
         tsconfigRootDir: import.meta.dirname,

diff --git a/examples/_tests/cases/basic.ts → examples/_tests/cases/basic.test.ts b/examples/_tests/cases/basic.ts → examples/_tests/cases/basic.test.ts
diff --git a/examples/_tests/cases/github.ts → examples/_tests/cases/github.test.ts b/examples/_tests/cases/github.ts → examples/_tests/cases/github.test.ts
diff --git a/examples/_tests/helpers/helpers.ts b/examples/_tests/helpers/helpers.ts
@@ -14,7 +14,7 @@ export const getPaths = (importMeta: ImportMeta): {
   examples: string,
 } => {
   const testModulePath = Path.parse(Url.fileURLToPath(importMeta.url))
-  const exampleName = testModulePath.name
+  const exampleName = Path.basename(testModulePath.base, `.test.ts`)
   const exampleDir = Path.join(examplesDir, exampleName)
   return {
     examples: examplesDir,

diff --git a/examples/_tests/helpers/test.ts b/examples/_tests/helpers/test.ts
@@ -5,14 +5,19 @@ import { $, type ProcessOutput } from 'zx'
 import type { Configurator } from '../../../src/configurator/_namespace.js'
 import type { ViteUserConfigWithPolen } from '../../../src/createConfiguration.js'
 
-const PolenSource = {
+export const PolenSource = {
   localLink: `localLink`,
   localFile: `localFile`,
   registry: `registry`,
 } as const
 
 export type PolenSource = (typeof PolenSource)[keyof typeof PolenSource]
 
+export const parsePolenSource = (value: string): PolenSource => {
+  if (value in PolenSource) return value as PolenSource
+  throw new Error(`Invalid Polen source: ${value}`)
+}
+
 export interface Fixtures {
   cwd: string
   /**
@@ -44,7 +49,11 @@ export const test = base.extend<Fixtures>({
     const output = await $({ cwd })`pnpm install`
     if (polenSource !== PolenSource.registry) {
       const protocol = polenSource === PolenSource.localLink ? `link` : `file`
-      await $({ cwd })`pnpm add polen@${protocol}:../..`
+      if (protocol === `link`) {
+        await $({ cwd })`pnpm link ../..`
+      } else {
+        await $({ cwd })`pnpm add polen@${protocol}:../..`
+      }
     }
     // eslint-disable-next-line
     await use(output)

diff --git a/examples/_tests/playwright.config.ts b/examples/_tests/playwright.config.ts
@@ -1,33 +1,31 @@
 import { defineConfig, devices } from 'playwright/test'
-import type { Fixtures } from './helpers/test.js'
+import { type Fixtures, parsePolenSource } from './helpers/test.js'
 
 const isCi = !!process.env[`CI`]
+const polenSource = process.env[`POLEN_SOURCE`]
+  ? parsePolenSource(process.env[`POLEN_SOURCE`])
+  : isCi
+  ? `localFile`
+  : undefined
 
 export default defineConfig<Fixtures>({
   name: `examples`,
   testDir: `./cases`,
-  testMatch: `*.ts`,
   fullyParallel: true,
   forbidOnly: isCi,
-  retries: isCi ? 2 : 0,
+  retries: isCi ? 0 : 0,
   workers: isCi ? 1 : undefined,
   outputDir: `./__results__`,
   // reporter: `html`,
   use: {
-    //   baseURL: `http://localhost:5173`,
     trace: `on-first-retry`,
     screenshot: `only-on-failure`,
-    polenSource: isCi ? `localFile` : undefined,
+    polenSource,
   },
   projects: [
     {
       name: `chromium`,
       use: { ...devices[`Desktop Chrome`] },
     },
   ],
-  // webServer: {
-  //   // We don't use the webServer config as we need more complex server management
-  //   // in our tests. Server starting and stopping is handled within the test files.
-  //   reuseExistingServer: true,
-  // },
 })
diff --git a/examples/basic/package.json b/examples/basic/package.json
@@ -3,16 +3,17 @@
   "private": true,
   "version": "0.0.0",
   "type": "module",
+  "packageManager": "pnpm@10.8.0",
   "scripts": {
     "dev": "vite",
     "build": "vite build --app",
     "start": "node dist/entry.js"
   },
   "devDependencies": {
     "typescript": "~5.8.3",
-    "vite": "^6.2.5"
+    "vite": "^6.2.6"
   },
   "dependencies": {
-    "polen": "^0.0.6"
+    "polen": "^0.1.0"
   }
 }