polen 0.11.0-next.14 → 0.11.0-next.15

package/src/vite/plugins/core.ts

@@ -0,0 +1,279 @@
+import { Content } from '#api/content/$'
+import { createNavbar, type NavbarItem } from '#api/content/navbar'
+import { Api } from '#api/index'
+import { Schema } from '#api/schema/$'
+import { VitePluginSelfContainedMode } from '#cli/_/self-contained-mode'
+import type { ReactRouter } from '#dep/react-router/index'
+import type { Vite } from '#dep/vite/index'
+import { Catalog } from '#lib/catalog/$'
+import { ViteVirtual } from '#lib/vite-virtual'
+import type { ProjectData } from '#project-data'
+import { debugPolen } from '#singletons/debug'
+import * as NodeFileSystem from '@effect/platform-node/NodeFileSystem'
+import { Json, Str } from '@wollybeard/kit'
+import { Effect } from 'effect'
+import { fileURLToPath } from 'node:url'
+import { polenVirtual } from '../vi.js'
+import { Pages } from './pages.js'
+import { SchemaAssets } from './schema-assets.js'
+
+const viTemplateVariables = polenVirtual([`template`, `variables`])
+const viTemplateSchemaAugmentations = polenVirtual([`template`, `schema-augmentations`])
+export const viProjectData = polenVirtual([`project`, `data.json`], { allowPluginProcessing: true })
+export const viProjectSchema = polenVirtual([`project`, `schema.json`], { allowPluginProcessing: true })
+export const viProjectHooks = polenVirtual([`project`, `hooks`], { allowPluginProcessing: true })
+
+export interface ProjectRoutesModule {
+  routes: ReactRouter.RouteObject[]
+}
+
+export const Core = (config: Api.Config.Config): Vite.PluginOption[] => {
+  let loadedCatalogCache: Api.Schema.InputSource.LoadedCatalog | null = null
+
+  const readSchema = async () => {
+    if (loadedCatalogCache === null) {
+      const loadedCatalog = await Effect.runPromise(
+        Schema.loadOrNull(config).pipe(
+          Effect.provide(NodeFileSystem.layer),
+        ),
+      )
+      loadedCatalogCache = loadedCatalog
+    }
+    return loadedCatalogCache
+  }
+
+  const plugins: Vite.Plugin[] = []
+
+  // Note: The main use for this right now is to resolve the react imports
+  // from the mdx vite plugin which have to go through the Polen exports since Polen keeps those deps bundled.
+  //
+  // If we manage to get the mdx vite plugin that defers JSX transform to Rolldown then we can remove this!
+  //
+  if (config.advanced.isSelfContainedMode) {
+    plugins.push(VitePluginSelfContainedMode({
+      projectDirPathExp: config.paths.project.rootDir,
+    }))
+  }
+
+  return [
+    ...plugins,
+    SchemaAssets(config),
+    /**
+     * If a `polen*` import is encountered from the user's project, resolve it to the currently
+     * running source code of Polen rather than the user's node_modules.
+     *
+     * Useful for the following cases:
+     *
+     * 1. Main: Using Polen CLI from the source code against some local example/development project.
+     *
+     * 2. Secondary: Using Polen CLI on a project that does not have Polen installed.
+     *    (User would likely not want to do this because they would not be able to achieve type safety)
+     */
+    {
+      name: `polen:internal-import-alias`,
+      enforce: `pre` as const,
+      resolveId(id, importer) {
+        // const debug = debugPolen.sub(`vite-plugin:internal-import-alias`)
+
+        const isPolenImporter = Boolean(
+          importer
+            && (
+              importer.startsWith(config.paths.framework.sourceDir)
+              || polenVirtual.includes(importer)
+              || (importer.startsWith(config.paths.framework.rootDir) && importer.endsWith(`index.html`))
+            ),
+        )
+
+        if (!isPolenImporter) return null
+        // debug(`check candidate`, { id, importer, isPolenImporter })
+
+        const find = Str.pattern<{ groups: [`path`] }>(/^#(?<path>.+)/)
+        const match = Str.match(id, find)
+        if (!match) return null
+
+        // Use Node's resolver to handle package.json imports correctly
+        try {
+          const resolved = import.meta.resolve(id)
+          const to = fileURLToPath(resolved)
+          // debug(`did resolve`, { from: id, to })
+          return to
+        } catch {
+          // If resolution fails, return null to let other resolvers handle it
+          return null
+        }
+      },
+    },
+    ...Pages({ config }),
+    {
+      name: `polen:core`,
+      config(_, { command }) {
+        return {
+          root: config.paths.framework.rootDir,
+          // todo
+          // future: {
+          //   removePluginHookHandleHotUpdate: 'warn',
+          //   removePluginHookSsrArgument: 'warn',
+          //   removeServerModuleGraph: 'warn',
+          //   removeServerHot: 'warn',
+          //   removeServerTransformRequest: 'warn',
+          //   removeSsrLoadModule: 'warn',
+          // },
+          define: {
+            __BUILDING__: Json.encode(command === `build`),
+            __SERVING__: Json.encode(command === `serve`),
+            __COMMAND__: Json.encode(command),
+            __BUILD_ARCHITECTURE__: Json.encode(config.build.architecture),
+            __BUILD_ARCHITECTURE_SSG__: Json.encode(config.build.architecture === `ssg`),
+            'process.env.NODE_ENV': Json.encode(config.advanced.debug ? 'development' : 'production'),
+          },
+          // customLogger: createLogger(config),
+          build: {
+            target: `esnext`,
+            assetsDir: config.paths.project.relative.build.relative.assets.root,
+            rollupOptions: {
+              treeshake: {
+                // Aggressive tree-shaking for smallest bundles
+                moduleSideEffects: false, // Only include code if an export is actually used
+                annotations: true, // Respect @__PURE__ annotations for better dead code elimination
+                unknownGlobalSideEffects: false, // Assume global functions don't have side effects
+              },
+            },
+            minify: !config.advanced.debug,
+            outDir: config.paths.project.absolute.build.root,
+            emptyOutDir: true, // disables warning that build dir not in root dir; expected b/c root dir = framework package
+          },
+        }
+      },
+      ...ViteVirtual.IdentifiedLoader.toHooks(
+        {
+          identifier: viProjectSchema,
+          async loader() {
+            const debug = debugPolen.sub(`module-project-schema`)
+            debug(`load`, { id: viProjectSchema.id })
+
+            const schemaResult = await readSchema()
+            if (!schemaResult || !schemaResult.data) {
+              return `export default null`
+            }
+
+            // Encode the catalog to convert GraphQLSchema to AST before serializing
+
+            const encodedCatalog = await Effect.runPromise(Catalog.encode(schemaResult.data))
+
+            return `export default ${JSON.stringify(encodedCatalog)}`
+          },
+        },
+        {
+          identifier: viTemplateVariables,
+          loader() {
+            const s = `export const templateVariables = ${JSON.stringify(config.templateVariables)}`
+            return s
+          },
+        },
+        {
+          identifier: viTemplateSchemaAugmentations,
+          loader() {
+            const s = `export const schemaAugmentations = ${JSON.stringify(config.schema?.augmentations ?? [])}`
+            return s
+          },
+        },
+        {
+          identifier: viProjectData,
+          async loader() {
+            const debug = debugPolen.sub(`module-project-data`)
+
+            debug(`load`, { id: viProjectData.id })
+
+            const loadedCatalog = await readSchema()
+
+            const navbar: NavbarItem[] = []
+
+            // ━ Schema presence causes adding some navbar items
+            if (loadedCatalog?.data) {
+              // IMPORTANT: Always ensure paths start with '/' for React Router compatibility.
+              // Without the leading slash, React Router treats paths as relative, which causes
+              // hydration mismatches between SSR (where base path is prepended) and client
+              // (where basename is configured). This ensures consistent behavior.
+              const referencePath = Api.Schema.Routing.createReferenceBasePath()
+              navbar.push({ pathExp: referencePath, title: `Reference`, position: 'left' })
+              // Check if we have revisions to show changelog
+              const catalog = loadedCatalog.data as Catalog.Catalog
+              const hasMultipleRevisions = Catalog.fold(
+                (versioned) => {
+                  // For versioned catalogs, count total revisions across all entries
+                  const totalRevisions = versioned.entries.reduce(
+                    (sum: number, entry) => sum + entry.revisions.length,
+                    0,
+                  )
+                  return totalRevisions > 1
+                },
+                (unversioned) => unversioned.schema.revisions?.length > 1,
+              )(catalog)
+
+              if (hasMultipleRevisions) {
+                navbar.push({ pathExp: `/changelog`, title: `Changelog`, position: 'right' })
+              }
+            }
+
+            //
+            // ━━ Scan pages and add to navbar
+            //
+
+            const pagesDir = config.paths.project.absolute.pages
+            const scanResult = await Effect.runPromise(
+              Content.scan({ dir: pagesDir }).pipe(
+                Effect.provide(NodeFileSystem.layer),
+              ),
+            )
+            const data = createNavbar(scanResult.list)
+            navbar.push(...data)
+
+            //
+            // ━━ Put It All together
+            //
+
+            const projectData: ProjectData = {
+              basePath: config.build.base,
+              paths: config.paths,
+              navbar, // Complete navbar with schema and pages
+              server: config.server,
+              warnings: config.warnings,
+            }
+
+            // Return a JavaScript module that exports the data
+            return `export default ${JSON.stringify(projectData)}`
+          },
+        },
+        {
+          identifier: viProjectHooks,
+          async loader() {
+            const fs = await import('node:fs/promises')
+            const path = await import('node:path')
+
+            const hooksPathTs = path.join(config.paths.project.rootDir, 'hooks.ts')
+            const hooksPathTsx = path.join(config.paths.project.rootDir, 'hooks.tsx')
+
+            let hooksPath = null
+            try {
+              await fs.access(hooksPathTsx)
+              hooksPath = hooksPathTsx
+            } catch {
+              try {
+                await fs.access(hooksPathTs)
+                hooksPath = hooksPathTs
+              } catch {
+                // No hooks file found
+              }
+            }
+
+            if (!hooksPath) {
+              return `export const navbar = null`
+            }
+
+            return `export * from '${hooksPath}'`
+          },
+        },
+      ),
+    },
+  ]
+}

package/src/vite/plugins/index.ts

@@ -0,0 +1,7 @@
+export { Branding } from './branding.js'
+export { Build } from './build.js'
+export { Core } from './core.js'
+export { Main } from './main.js'
+export { Pages } from './pages.js'
+export { SchemaAssets } from './schema-assets.js'
+export { Serve } from './serve.js'

package/src/vite/plugins/main.ts

@@ -0,0 +1,42 @@
+import type { Api } from '#api/index'
+import type { Vite } from '#dep/vite/index'
+import { Manifest } from '#vite/plugins/manifest'
+import { vitePluginSsrCss } from '@hiogawa/vite-plugin-ssr-css'
+import ViteReact from '@vitejs/plugin-react-oxc'
+import { Path } from '@wollybeard/kit'
+import Inspect from 'vite-plugin-inspect'
+import { Branding } from './branding.js'
+import { Build } from './build.js'
+import { Core } from './core.js'
+import { Serve } from './serve.js'
+
+export const Main = (
+  config: Api.Config.Config,
+): Vite.PluginOption => {
+  const plugins: Vite.PluginOption = []
+
+  // Optional Plugins based on config
+
+  if (config.advanced.explorer) {
+    const outputDir = Path.join(config.paths.project.rootDir, `.bundle-explorer`)
+    const plugin = Inspect({
+      build: true,
+      outputDir,
+    })
+    plugins.push(plugin)
+  }
+
+  plugins.push(
+    ViteReact(),
+    vitePluginSsrCss({
+      entries: [`/${config.paths.framework.template.relative.client.entrypoint}`],
+    }),
+    Branding(config),
+    Manifest(config),
+    Serve(config),
+    Core(config),
+    Build(config),
+  )
+
+  return plugins
+}

package/src/vite/plugins/manifest.ts

@@ -0,0 +1,36 @@
+import type { Api } from '#api/index'
+import { Vite } from '#dep/vite/index'
+import { ViteVirtual } from '#lib/vite-virtual'
+import { Path } from '@wollybeard/kit'
+import { polenVirtual } from '../vi.js'
+
+const viClientManifest = polenVirtual([`vite`, `client`, `manifest`])
+
+export const Manifest = (config: Api.Config.Config): Vite.Plugin => {
+  let configEnv: Vite.ConfigEnv
+
+  return {
+    name: `polen-manifest`,
+    config(_, configEnv_) {
+      configEnv = configEnv_
+    },
+    ...ViteVirtual.IdentifiedLoader.toHooks(
+      {
+        identifier: viClientManifest,
+        loader: async () => {
+          // In development just return an empty manifest
+          if (configEnv.mode === Vite.ModeName.development) {
+            return `export default {}`
+          }
+
+          const manifestPath = Path.join(config.paths.project.absolute.build.root, `.vite`, `manifest.json`)
+          const module = await import(manifestPath, { with: { type: `json` } }) as {
+            default: Vite.Manifest
+          }
+
+          return `export default ${JSON.stringify(module.default)}`
+        },
+      },
+    ),
+  }
+}

package/src/vite/plugins/pages.ts

@@ -0,0 +1,266 @@
+import { Content } from '#api/content/$'
+import type { Api } from '#api/index'
+import type { Vite } from '#dep/vite/index'
+import { FileRouter } from '#lib/file-router'
+import { reportDiagnostics } from '#lib/file-router/diagnostic-reporter'
+import { debugPolen } from '#singletons/debug'
+import * as NodeFileSystem from '@effect/platform-node/NodeFileSystem'
+import mdx from '@mdx-js/rollup'
+import { Arr, Cache, Path, Str } from '@wollybeard/kit'
+import { recmaCodeHike, remarkCodeHike } from 'codehike/mdx'
+import { Effect } from 'effect'
+import remarkFrontmatter from 'remark-frontmatter'
+import remarkGfm from 'remark-gfm'
+import { polenVirtual } from '../vi.js'
+import { viProjectData } from './core.js'
+
+const debug = debugPolen.sub(`vite-pages`)
+
+export const viProjectRoutes = polenVirtual([`project`, `routes.jsx`], { allowPluginProcessing: true })
+export const viProjectPagesCatalog = polenVirtual([`project`, `data`, `pages-catalog.json`], {
+  allowPluginProcessing: true,
+})
+
+export interface Options {
+  config: Api.Config.Config
+}
+
+export interface ProjectPagesCatalog {
+  sidebarIndex: Content.SidebarIndex
+  pages: Content.Page[]
+}
+
+/**
+ * Pages plugin with tree support
+ */
+export const Pages = ({
+  config,
+}: Options): Vite.Plugin[] => {
+  const scanPages = Cache.memoize(debug.trace(async function scanPages() {
+    const result = await Effect.runPromise(
+      Content.scan({
+        dir: config.paths.project.absolute.pages,
+        glob: `**/*.{md,mdx}`,
+      }).pipe(
+        Effect.provide(NodeFileSystem.layer),
+      ),
+    )
+    return result
+  }))
+
+  const invalidateVirtualModules = (server: Vite.ViteDevServer) => {
+    const routesModule = server.moduleGraph.getModuleById(viProjectRoutes.id)
+    if (routesModule) {
+      server.moduleGraph.invalidateModule(routesModule)
+      debug(`Invalidated routes virtual module`)
+    }
+
+    const catalogModule = server.moduleGraph.getModuleById(viProjectPagesCatalog.id)
+    if (catalogModule) {
+      server.moduleGraph.invalidateModule(catalogModule)
+      debug(`Invalidated pages catalog virtual module`)
+    }
+
+    const projectDataModule = server.moduleGraph.getModuleById(viProjectData.id)
+    if (projectDataModule) {
+      server.moduleGraph.invalidateModule(projectDataModule)
+      debug(`Invalidated project data virtual module`)
+    }
+  }
+
+  const generateRoutesModule = (pages: Content.Page[]): string => {
+    const $ = {
+      routes: `routes`,
+    }
+
+    const s = Str.Builder()
+    s`export const ${$.routes} = []`
+
+    // Generate imports and route objects
+    for (const { route, metadata } of pages) {
+      const filePathExp = Path.format(route.file.path.absolute)
+      const pathExp = FileRouter.routeToPathExpression(route)
+      const $$ = {
+        ...$,
+        Component: Str.Case.camel(`page ` + Str.titlizeSlug(pathExp)),
+      }
+
+      s`
+        import ${$$.Component} from '${filePathExp}'
+
+        ${$$.routes}.push({
+          path: '${pathExp}',
+          Component: ${$$.Component},
+          metadata: ${JSON.stringify(metadata)}
+        })
+      `
+    }
+
+    return s.render()
+  }
+
+  const chConfig = {
+    components: { code: 'CodeBlock' },
+    syntaxHighlighting: {
+      theme: `github-light`,
+    },
+  }
+
+  return [
+    // Plugin 1: MDX Processing
+    {
+      enforce: `pre`,
+      ...mdx({
+        jsxImportSource: `polen/react`,
+        providerImportSource: `polen/mdx`,
+        remarkPlugins: [
+          // Parse frontmatter blocks so they're removed from content
+          remarkFrontmatter,
+          remarkGfm,
+          [remarkCodeHike, chConfig],
+        ],
+        recmaPlugins: [
+          [recmaCodeHike, chConfig],
+        ],
+        rehypePlugins: [],
+      }),
+    },
+
+    // Plugin 2: Pages Management
+    {
+      name: `polen:pages`,
+
+      // Dev server configuration
+      configureServer(server) {
+        // Add pages directory to watcher
+        debug(`configureServer: watch pages directory`, config.paths.project.absolute.pages)
+        server.watcher.add(config.paths.project.absolute.pages)
+
+        // Handle file additions and deletions
+        const handleFileStructureChange = async (file: string, event: `add` | `unlink`) => {
+          if (!Content.isPageFile(file, config.paths.project.absolute.pages)) return
+
+          debug(`Page file ${event === `add` ? `added` : `deleted`}:`, file)
+
+          // Clear cache and rescan
+          scanPages.clear()
+          const newScanResult = await scanPages()
+
+          // Invalidate virtual modules
+          invalidateVirtualModules(server)
+
+          // Report any diagnostics
+          reportDiagnostics(newScanResult.diagnostics)
+
+          // Trigger full reload to ensure routes are updated
+          server.ws.send({ type: `full-reload` })
+        }
+
+        server.watcher.on(`add`, (file) => handleFileStructureChange(file, `add`))
+        server.watcher.on(`unlink`, (file) => handleFileStructureChange(file, `unlink`))
+      },
+
+      // Hot update handling for existing files
+      async handleHotUpdate({ file, server, modules }) {
+        debug(`handleHotUpdate`, file)
+        if (!Content.isPageFile(file, config.paths.project.absolute.pages)) return
+
+        debug(`Page file changed:`, file)
+
+        // Get current pages before clearing cache
+        const oldPages = await scanPages()
+
+        // Clear cache and rescan
+        scanPages.clear()
+        const newScanResult = await scanPages()
+
+        // Check if the visible pages list changed. This can happen when:
+        // - A page's frontmatter `hidden` field changes (true <-> false)
+        // - A page's frontmatter affects its route (though we don't support this yet)
+        // If only the content changed (not frontmatter), we can use fast HMR.
+        const pageStructureChanged = !oldPages || !Arr.equalShallowly(
+          oldPages.list.map(p => Path.format(p.route.file.path.absolute)),
+          newScanResult.list.map(p => Path.format(p.route.file.path.absolute)),
+        )
+
+        if (!pageStructureChanged) {
+          debug(`Page content changed, allowing HMR`)
+          // Let default HMR handle the MDX file change
+          return modules
+        }
+
+        //
+        // ━━ Manual Invalidation
+        //
+
+        debug(`Page structure changed, triggering full reload`)
+
+        // Invalidate virtual modules and trigger reload
+        invalidateVirtualModules(server)
+        reportDiagnostics(newScanResult.diagnostics)
+        server.ws.send({ type: `full-reload` })
+        return []
+      },
+      resolveId(id) {
+        if (id === viProjectPagesCatalog.id) {
+          return viProjectPagesCatalog.resolved
+        }
+      },
+      load: {
+        async handler(id) {
+          if (id !== viProjectPagesCatalog.resolved) return
+          debug(`hook load`)
+
+          const scanResult = await scanPages()
+
+          reportDiagnostics(scanResult.diagnostics)
+          debug(`found visible`, { count: scanResult.list.length })
+
+          //
+          // ━━ Build Sidebar
+          //
+
+          const sidebarIndex = Content.buildSidebarIndex(scanResult)
+
+          //
+          // ━━ Put It All together
+          //
+
+          const projectPagesCatalog: ProjectPagesCatalog = {
+            sidebarIndex,
+            pages: scanResult.list,
+          }
+
+          // Return a JavaScript module that exports the data
+          return `export default ${JSON.stringify(projectPagesCatalog)}`
+        },
+      },
+    },
+    // Plugin 3: Virtual Module for React Router Routes
+    {
+      name: `polen:routes`,
+      resolveId(id) {
+        if (id === viProjectRoutes.id) {
+          return viProjectRoutes.resolved
+        }
+      },
+      load: {
+        handler: async (id) => {
+          if (id !== viProjectRoutes.resolved) return
+
+          debug(`Loading viProjectRoutes virtual module`)
+
+          const scanResult = await scanPages()
+          reportDiagnostics(scanResult.diagnostics)
+          const code = generateRoutesModule(scanResult.list)
+
+          // Generate the module code
+          return {
+            code,
+            moduleType: `js`,
+          }
+        },
+      },
+    },
+  ]
+}