polen 0.10.0-next.9 → 0.11.0-next.1

package/src/api/config/configurator.ts

@@ -1,10 +1,10 @@
 import type { Vite } from '#dep/vite/index'
 import { assertPathAbsolute } from '#lib/kit-temp'
 import { type PackagePaths, packagePaths } from '#package-paths'
-import { Path } from '@wollybeard/kit'
+import { Err, Manifest, Path, Str } from '@wollybeard/kit'
 import { z } from 'zod'
-import type { SchemaAugmentation } from '../../api/schema-augmentation/index.ts'
-import type { Schema } from '../schema/index.ts'
+import type { SchemaAugmentation } from '../../api/schema-augmentation/index.js'
+import type { Schema } from '../schema/index.js'
 
 export const BuildArchitectureEnum = {
   ssg: `ssg`,
@@ -18,23 +18,71 @@ export type BuildArchitecture = typeof BuildArchitectureEnum[keyof typeof BuildA
 
 type SchemaConfigInput = Omit<Schema.Config, `projectRoot`>
 
+/**
+ * Polen configuration input.
+ *
+ * All options are optional. Polen provides sensible defaults for a great developer experience out of the box.
+ */
 export interface ConfigInput {
   /**
-   * Path to the root directory of your project.
+   * Configuration for how Polen loads your GraphQL schema.
    *
-   * Relative paths will be resolved relative to this config file.
+   * Polen supports multiple schema sources:
+   * - `file` - Load from a single SDL file (default: schema.graphql)
+   * - `directory` - Load multiple SDL files with date prefixes (enables changelog)
+   * - `memory` - Define schemas programmatically in configuration
    *
-   * @default The directory where the config file is located.
+   * @example
+   * ```ts
+   * // Single file
+   * schema: {
+   *   useDataSources: 'file',
+   *   dataSources: {
+   *     file: { path: './my-schema.graphql' }
+   *   }
+   * }
+   *
+   * // Multiple versions for changelog
+   * schema: {
+   *   useDataSources: 'directory',
+   *   dataSources: {
+   *     directory: { path: './schema' }
+   *   }
+   * }
+   * ```
    */
-  root?: string
+  schema?: SchemaConfigInput
   /**
-   * Enable a special module explorer for the source code that Polen assembles for your app.
+   * Programmatically enhance your GraphQL schema documentation without modifying the schema files.
    *
-   * Powered by [Vite Inspect](https://github.com/antfu-collective/vite-plugin-inspect).
+   * Perfect for adding implementation details, usage examples, deprecation notices,
+   * or any additional context that helps developers understand your API better.
    *
-   * @default true
+   * @example
+   * ```ts
+   * schemaAugmentations: [
+   *   {
+   *     type: 'description',
+   *     on: {
+   *       type: 'TargetType',
+   *       name: 'User'
+   *     },
+   *     placement: 'after',
+   *     content: '\n\nSee the [User Guide](/guides/users) for detailed usage.'
+   *   },
+   *   {
+   *     type: 'description',
+   *     on: {
+   *       type: 'TargetField',
+   *       targetType: 'Query',
+   *       name: 'users'
+   *     },
+   *     placement: 'after',
+   *     content: '\n\n**Rate limit:** 100 requests per minute'
+   *   }
+   * ]
+   * ```
    */
-  schema?: SchemaConfigInput
   schemaAugmentations?: SchemaAugmentation.Augmentation[]
   templateVariables?: {
     /**
@@ -42,21 +90,52 @@ export interface ConfigInput {
      *
      * Used in the navigation bar and in the title tag.
      *
-     * @default `My Developer Portal`
+     * If not provided, Polen will try to use your project's package.json name
+     * field, converting it to title case (e.g., "my-project" → "My Project").
+     *
+     * @default Your package.json name (title-cased) or "My Developer Portal"
+     * @example
+     * ```ts
+     * // Explicit title
+     * title: 'Acme GraphQL API'
+     *
+     * // Falls back to package.json name
+     * // If package.json has { "name": "acme-graphql" }
+     * // Title will be "Acme Graphql"
+     * ```
      */
     title?: string
   }
+  /**
+   * Build configuration for your developer portal.
+   */
   build?: {
+    /**
+     * The build architecture for your developer portal.
+     *
+     * - `ssg` - Static Site Generation: Pre-renders all pages at build time. Best for public docs.
+     * - `ssr` - Server-Side Rendering: Renders pages on each request. Enables dynamic features.
+     * - `spa` - Single Page Application: Client-side rendering only.
+     *
+     * @default 'ssg'
+     */
     architecture?: BuildArchitecture
     /**
      * Base public path for the deployed site.
      *
      * Use this when deploying to a subdirectory (e.g., GitHub Pages project sites).
      *
-     * Examples:
-     * - `/` (default) - Deploy to root
-     * - `/my-project/` - Deploy to subdirectory
-     * - `/pr-123/` - PR preview deployments
+     * @example
+     * ```ts
+     * // Deploy to root
+     * base: '/'
+     *
+     * // Deploy to subdirectory
+     * base: '/my-project/'
+     *
+     * // PR preview deployments
+     * base: '/pr-123/'
+     * ```
      *
      * Must start and end with `/`.
      *
@@ -64,7 +143,86 @@ export interface ConfigInput {
      */
     base?: string
   }
+  /**
+   * Server configuration for development and production.
+   */
+  server?: {
+    /**
+     * Port for the server to listen on.
+     *
+     * - In development: The port for the Vite dev server
+     * - In production SSR: The default port for the Node.js server
+     *
+     * For production SSR builds, this can be overridden at runtime
+     * using the PORT environment variable.
+     *
+     * @default 3000
+     * @example
+     * ```ts
+     * // Use a specific port
+     * server: {
+     *   port: 4000
+     * }
+     *
+     * // Or via CLI flags:
+     * // polen dev --port 4000
+     * // polen build --port 4000
+     * ```
+     */
+    port?: number
+  }
+  /**
+   * Configuration for developer experience warnings.
+   *
+   * Polen can show helpful warnings for common issues or misconfigurations.
+   * Each warning type can be individually enabled or disabled.
+   *
+   * @example
+   * ```ts
+   * warnings: {
+   *   interactiveWithoutSchema: {
+   *     enabled: false // Disable warning when interactive code blocks are used without a schema
+   *   }
+   * }
+   * ```
+   */
+  warnings?: {
+    /**
+     * Warning shown when GraphQL code blocks have the `interactive` flag
+     * but no schema is configured.
+     *
+     * Interactive features require a schema to provide field validation,
+     * type information, and auto-completion.
+     *
+     * @default { enabled: true }
+     */
+    interactiveWithoutSchema?: {
+      /**
+       * Whether to show this warning.
+       *
+       * @default true
+       */
+      enabled?: boolean
+    }
+  }
+  /**
+   * Advanced configuration options.
+   *
+   * These settings are for advanced use cases and debugging.
+   */
   advanced?: {
+    /**
+     * Enable a special module explorer for the source code that Polen assembles for your app.
+     *
+     * This opens an interactive UI to inspect the module graph and transformations.
+     * Useful for debugging build issues or understanding Polen's internals.
+     *
+     * Access the explorer at `/__inspect/` when running the dev server.
+     *
+     * Powered by [Vite Inspect](https://github.com/antfu-collective/vite-plugin-inspect).
+     *
+     * @default false
+     */
     explorer?: boolean
     /**
      * Force the CLI to resolve Polen imports in your project to itself rather than
@@ -131,6 +289,13 @@ const buildPaths = (rootDir: string): Config[`paths`] => {
 
   const publicAbsolutePath = rootAbsolute(`public`)
   const publicAbsolute = Path.ensureAbsoluteWith(publicAbsolutePath)
+
+  const assetsAbsolute = Path.ensureAbsoluteWith(buildAbsolute(`assets`))
+
+  // Dev assets paths
+  const devAssetsRelative = 'node_modules/.vite/polen-assets'
+  const devAssetsAbsolute = Path.join(packagePaths.rootDir, devAssetsRelative)
+
   return {
     project: {
       rootDir,
@@ -139,29 +304,44 @@ const buildPaths = (rootDir: string): Config[`paths`] => {
           root: `build`,
           relative: {
             serverEntrypoint: `app.js`,
-            assets: `assets`,
+            assets: {
+              root: `assets`,
+              relative: {
+                schemas: `schemas`,
+              },
+            },
           },
         },
         pages: `pages`,
         public: {
-          root: 'public',
-          logo: 'logo.svg',
+          root: `public`,
+          logo: `logo.svg`,
         },
       },
       absolute: {
         pages: rootAbsolute(`pages`),
         build: {
-          root: buildAbsolute('.'),
+          root: buildAbsolute(`.`),
           serverEntrypoint: buildAbsolute(`app.js`),
-          assets: buildAbsolute(`assets`),
+          assets: {
+            root: buildAbsolute(`assets`),
+            schemas: assetsAbsolute(`schemas`),
+          },
         },
         public: {
-          root: publicAbsolute('.'),
-          logo: publicAbsolute('logo.svg'),
+          root: publicAbsolute(`.`),
+          logo: publicAbsolute(`logo.svg`),
         },
       },
     },
-    framework: packagePaths,
+    framework: {
+      ...packagePaths,
+      devAssets: {
+        relative: devAssetsRelative,
+        absolute: devAssetsAbsolute,
+        schemas: Path.join(devAssetsAbsolute, 'schemas'),
+      },
+    },
   }
 }
 
@@ -171,6 +351,12 @@ export interface Config {
     architecture: BuildArchitecture
     base: string
   }
+  server: {
+    port: number
+    routes: {
+      assets: string
+    }
+  }
   watch: {
     also: string[]
   }
@@ -180,6 +366,11 @@ export interface Config {
   ssr: {
     enabled: boolean
   }
+  warnings: {
+    interactiveWithoutSchema: {
+      enabled: boolean
+    }
+  }
   paths: {
     project: {
       rootDir: string
@@ -187,7 +378,12 @@ export interface Config {
         build: {
           root: string
           relative: {
-            assets: string
+            assets: {
+              root: string
+              relative: {
+                schemas: string
+              }
+            }
             serverEntrypoint: string
           }
         }
@@ -200,7 +396,10 @@ export interface Config {
       absolute: {
         build: {
           root: string
-          assets: string
+          assets: {
+            root: string
+            schemas: string
+          }
           serverEntrypoint: string
         }
         pages: string
@@ -210,7 +409,13 @@ export interface Config {
         }
       }
     }
-    framework: PackagePaths
+    framework: PackagePaths & {
+      devAssets: {
+        relative: string
+        absolute: string
+        schemas: string
+      }
+    }
   }
   advanced: {
     isSelfContainedMode: boolean
@@ -233,10 +438,21 @@ const configInputDefaults: Config = {
     architecture: BuildArchitecture.enum.ssg,
     base: `/`,
   },
+  server: {
+    port: 3000,
+    routes: {
+      assets: '/assets',
+    },
+  },
   schema: null,
   ssr: {
     enabled: true,
   },
+  warnings: {
+    interactiveWithoutSchema: {
+      enabled: true,
+    },
+  },
   paths: buildPaths(process.cwd()),
   advanced: {
     isSelfContainedMode: false,
@@ -256,7 +472,6 @@ export const normalizeInput = async (
    * If this is omitted, then relative root paths will throw an error.
    */
   baseRootDirPath: string,
-  // eslint-disable-next-line
 ): Promise<Config> => {
   assertPathAbsolute(baseRootDirPath)
 
@@ -286,16 +501,19 @@ export const normalizeInput = async (
     config.advanced.debug = configInput.advanced.debug
   }
 
-  if (configInput?.root !== undefined) {
-    if (!baseRootDirPath && !Path.isAbsolute(configInput.root)) {
-      throw new Error(
-        `Root path must be absolute or baseRootPath must be provided to resolve relative root paths. Provided: ${configInput.root}`,
-      )
+  // Always use the baseRootDirPath as the project root
+  // This is either the --project directory or the config file directory
+  config.paths = buildPaths(baseRootDirPath)
+
+  // Try to read package.json name as fallback for title
+  if (!configInput?.templateVariables?.title) {
+    const packageJson = await Manifest.resource.read(config.paths.project.rootDir)
+
+    // todo: let the user know there was an error...
+    if (!Err.is(packageJson) && packageJson.name) {
+      // Package name will be used as default, but can still be overridden below
+      config.templateVariables.title = Str.Case.title(packageJson.name)
     }
-    const root = Path.ensureAbsolute(configInput.root, baseRootDirPath)
-    config.paths = buildPaths(root)
-  } else if (baseRootDirPath) {
-    config.paths = buildPaths(baseRootDirPath)
   }
 
   if (configInput?.advanced?.vite) {
@@ -327,5 +545,17 @@ export const normalizeInput = async (
     config.watch.also = configInput.advanced.watch.also
   }
 
+  if (configInput?.server?.port !== undefined) {
+    config.server.port = configInput.server.port
+  }
+
+  // Server routes are not configurable by users yet, use defaults
+  // config.server.routes is already set from defaultConfig
+
+  // Process warnings configuration
+  if (configInput?.warnings?.interactiveWithoutSchema?.enabled !== undefined) {
+    config.warnings.interactiveWithoutSchema.enabled = configInput.warnings.interactiveWithoutSchema.enabled
+  }
+
   return config
 }

package/src/api/config/define.ts

@@ -1,5 +1,5 @@
 import { Fn } from '@wollybeard/kit'
-import type { ConfigInput } from './configurator.ts'
+import type { ConfigInput } from './configurator.js'
 
 /**
  * Define a Polen configuration.

package/src/api/config/index.ts

@@ -1 +1 @@
-export * as Config from './config.ts'
+export * as Config from './config.js'

package/src/api/config/load.ts

@@ -5,7 +5,7 @@ import { debugPolen } from '#singletons/debug'
 import type { Prom } from '@wollybeard/kit'
 import { Path } from '@wollybeard/kit'
 import * as Module from 'node:module'
-import type { ConfigInput } from './configurator.ts'
+import type { ConfigInput } from './configurator.js'
 
 export const fileNameBases = [`polen.config`, `.polen.config`]
 export const fileNameExtensionsTypeScript = [`.ts`, `.js`, `.mjs`, `.mts`]
@@ -55,16 +55,13 @@ export const load = async (options: LoadOptions): Promise<ConfigInput> => {
     configInput = {}
   } else {
     // If the user's config is a TypeScript file, we will use TSX to import it.
-    // TODO: Use NodeJS's native ESM support for TypeScript files.
 
     let module: { default?: Prom.Maybe<ConfigInput>; config?: Prom.Maybe<ConfigInput> }
     if (fileNameExtensionsTypeScript.some(_ => filePath.endsWith(_))) {
       // @see https://tsx.is/dev-api/ts-import#usage
       const { tsImport } = await import(`tsx/esm/api`)
-      // eslint-disable-next-line
       module = await tsImport(filePath, import.meta.url)
     } else {
-      // eslint-disable-next-line
       module = await import(filePath)
     }
     debug(`imported config module`)

package/src/api/config/merge.ts

@@ -1,5 +1,6 @@
 import { Vite } from '#dep/vite/index'
-import type { ConfigInput } from './configurator.ts'
+import { spreadShallow } from '#lib/kit-temp'
+import type { ConfigInput } from './configurator.js'
 
 /**
  * Deep merge two Polen config inputs.
@@ -7,47 +8,55 @@ import type { ConfigInput } from './configurator.ts'
  */
 export const mergeInputs = (
   base: ConfigInput,
-  // eslint-disable-next-line
   overrides?: ConfigInput | undefined,
 ): ConfigInput => {
   if (!overrides) {
     return base
   }
 
-  const merged: ConfigInput = {
-    ...base,
-    ...overrides,
-  }
+  const merged: ConfigInput = spreadShallow(base, overrides)
 
   // Merge schema if both have it
-  if (base.schema || overrides.schema) {
+  if (base.schema ?? overrides.schema) {
     merged.schema = overrides.schema ?? base.schema
   }
 
   // Merge build config
-  if (base.build || overrides.build) {
-    merged.build = {
-      ...base.build,
-      ...overrides.build,
+  if (base.build ?? overrides.build) {
+    merged.build = spreadShallow(base.build, overrides.build)
+  }
+
+  // Merge server config
+  if (base.server ?? overrides.server) {
+    merged.server = spreadShallow(base.server, overrides.server)
+  }
+
+  // Merge warnings config
+  if (base.warnings ?? overrides.warnings) {
+    merged.warnings = spreadShallow(base.warnings, overrides.warnings)
+
+    // Merge interactiveWithoutSchema config
+    if (base.warnings?.interactiveWithoutSchema ?? overrides.warnings?.interactiveWithoutSchema) {
+      merged.warnings.interactiveWithoutSchema = spreadShallow(
+        base.warnings?.interactiveWithoutSchema,
+        overrides.warnings?.interactiveWithoutSchema,
+      )
     }
   }
 
   // Merge advanced config
-  if (base.advanced || overrides.advanced) {
-    merged.advanced = {
-      ...base.advanced,
-      ...overrides.advanced,
-    }
+  if (base.advanced ?? overrides.advanced) {
+    merged.advanced = spreadShallow(base.advanced, overrides.advanced)
 
     // Merge advanced.watch config
-    if (base.advanced?.watch || overrides.advanced?.watch) {
-      merged.advanced.watch = {
-        ...base.advanced?.watch,
-        ...overrides.advanced?.watch,
-      }
+    if (base.advanced?.watch ?? overrides.advanced?.watch) {
+      merged.advanced.watch = spreadShallow(
+        base.advanced?.watch,
+        overrides.advanced?.watch,
+      )
 
       // Merge watch.also arrays
-      if (base.advanced?.watch?.also || overrides.advanced?.watch?.also) {
+      if (base.advanced?.watch?.also ?? overrides.advanced?.watch?.also) {
         merged.advanced.watch.also = [
           ...(base.advanced?.watch?.also ?? []),
           ...(overrides.advanced?.watch?.also ?? []),

package/src/api/config-resolver/config-resolver.ts

@@ -1,2 +1,2 @@
-export * from './resolve.ts'
-export * from './vite.ts'
+export * from './resolve.js'
+export * from './vite.js'

package/src/api/config-resolver/index.ts

@@ -1 +1 @@
-export * as ConfigResolver from './config-resolver.ts'
+export * as ConfigResolver from './config-resolver.js'

package/src/api/config-resolver/resolve.ts

@@ -1,8 +1,8 @@
 import { debugPolen } from '#singletons/debug'
-import { type ConfigInput, normalizeInput } from '../config/configurator.ts'
-import { load, type LoadOptions } from '../config/load.ts'
-import { mergeInputs } from '../config/merge.ts'
-import { toViteUserConfig, type ViteUserConfigWithPolen } from './vite.ts'
+import { type ConfigInput, normalizeInput } from '../config/configurator.js'
+import { load, type LoadOptions } from '../config/load.js'
+import { mergeInputs } from '../config/merge.js'
+import { toViteUserConfig, type ViteUserConfigWithPolen } from './vite.js'
 
 interface ResolveFromFileOptions extends LoadOptions {
   overrides?: ConfigInput

package/src/api/config-resolver/vite.ts

@@ -1,6 +1,6 @@
 import { Main } from '#api/vite/plugins/main'
 import { Vite } from '#dep/vite/index'
-import type { Config } from '../config/configurator.ts'
+import type { Config } from '../config/configurator.js'
 
 /**
  * Transform Polen config input into a Vite configuration.

package/src/api/content/$$.ts

@@ -1,5 +1,6 @@
-export * from './metadata.ts'
-export * from './navbar.ts'
-export * from './page.ts'
-export * from './scan.ts'
-export * from './sidebar.ts'
+export * from './metadata.js'
+export * from './navbar.js'
+export * from './page.js'
+export * from './scan.js'
+export * from './sidebar.js'
+export * from './utils.js'

package/src/api/content/$.test.ts

@@ -1,6 +1,6 @@
 import { Fs, Path } from '@wollybeard/kit'
 import { afterEach, beforeEach, describe, expect, test } from 'vitest'
-import { Content } from './$.ts'
+import { Content } from './$.js'
 
 describe('content', () => {
   let testDir: string

package/src/api/content/$.ts

@@ -1 +1 @@
-export * as Content from './$$.ts'
+export * as Content from './$$.js'

package/src/api/content/navbar.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest'
-import { createNavbar } from './navbar.ts'
-import type { Page } from './page.ts'
+import { createNavbar } from './navbar.js'
+import type { Page } from './page.js'
 
 const createPage = (path: string[], fileName = 'index', hidden = false): Page => ({
   route: {

package/src/api/content/navbar.ts

@@ -1,5 +1,5 @@
 import { Str } from '@wollybeard/kit'
-import type { Page } from './page.ts'
+import type { Page } from './page.js'
 
 export interface NavbarItem {
   pathExp: string
@@ -33,12 +33,12 @@ export const createNavbar = (pages: Page[]): NavbarItem[] => {
     // For directories, check if there's an index page
     const indexPage = pages.find(p =>
       p.route.logical.path.length === 1
-      && p.route.file.path.relative.name === 'index'
+      && p.route.file.path.relative.name === `index`
     )
 
     // For single non-index files at top level
     const singlePage = pages.length === 1 && pages[0]!.route.logical.path.length === 1
-      && pages[0]!.route.file.path.relative.name !== 'index'
+      && pages[0]!.route.file.path.relative.name !== `index`
 
     // Include in navbar if:
     // 1. It's a directory with an index page, OR

package/src/api/content/page.ts

@@ -1,5 +1,5 @@
 import type { FileRouter } from '#lib/file-router/index'
-import type { Metadata } from './metadata.ts'
+import type { Metadata } from './metadata.js'
 
 export type { Metadata }