polen 0.9.0-next.5 → 0.9.0-next.7

package/build/template/server/ssg/generate.js.map

@@ -1 +1 @@
-{"version":3,"file":"generate.js","sourceRoot":"","sources":["../../../../src/template/server/ssg/generate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAA;AAEtC,OAAO,EAAE,GAAG,EAAE,MAAM,sBAAsB,CAAA;AAC1C,OAAO,KAAK,MAAM,MAAM,kBAAkB,CAAA;AAC1C,OAAO,YAAY,MAAM,sCAAsC,CAAA;AAC/D,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAC/C,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAErD,MAAM,CAAC,MAAM,QAAQ,GAAG,KAAK,EAAE,IAA+B,EAAE,EAAE;IAChE,MAAM,OAAO,GAAiB,KAAK,EAAE,GAAG,EAAE,EAAE;QAC1C,MAAM,oBAAoB,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QAC1D,IAAI,oBAAoB,YAAY,QAAQ,EAAE,CAAC;YAC7C,OAAO,oBAAoB,CAAA;QAC7B,CAAC;QACD,OAAO,UAAU,CAAC,oBAAoB,CAAC,CAAA;IACzC,CAAC,CAAA;IAED,MAAM,UAAU,GAAG,cAAc,EAAE,CAAA;IAEnC,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,GAAG,CAAC,GAAG,CAAC,SAAS,EAAE,OAAO,CAAC,CAAA;IAC7B,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE;QAC/C,WAAW,EAAE,EAAE;QACf,GAAG,EAAE,YAAY,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI;KAC5C,CAAC,CAAA;IAEF,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,IAAI,KAAK,CAAC,gCAAgC,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAA;IAC5E,CAAC;AACH,CAAC,CAAA"}
+{"version":3,"file":"generate.js","sourceRoot":"","sources":["../../../../src/template/server/ssg/generate.ts"],"names":[],"mappings":"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"}

package/build/template/server/view.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"view.d.ts","sourceRoot":"","sources":["../../../src/template/server/view.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,IAAI,sCAA8B,CAAA"}
+{"version":3,"file":"view.d.ts","sourceRoot":"","sources":["../../../src/template/server/view.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,IAAI,sCAEf,CAAA"}

package/build/template/server/view.js

@@ -1,4 +1,7 @@
 import { createStaticHandler } from 'react-router';
+import PROJECT_DATA from 'virtual:polen/project/data.jsonsuper';
 import { routes } from '../routes.jsx';
-export const view = createStaticHandler(routes);
+export const view = createStaticHandler(routes, {
+    basename: PROJECT_DATA.basePath === `/` ? undefined : PROJECT_DATA.basePath.slice(0, -1), // Remove trailing slash for React Router
+});
 //# sourceMappingURL=view.js.map

package/build/template/server/view.js.map

@@ -1 +1 @@
-{"version":3,"file":"view.js","sourceRoot":"","sources":["../../../src/template/server/view.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAA;AAClD,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAEtC,MAAM,CAAC,MAAM,IAAI,GAAG,mBAAmB,CAAC,MAAM,CAAC,CAAA"}
+{"version":3,"file":"view.js","sourceRoot":"","sources":["../../../src/template/server/view.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAA;AAClD,OAAO,YAAY,MAAM,sCAAsC,CAAA;AAC/D,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAEtC,MAAM,CAAC,MAAM,IAAI,GAAG,mBAAmB,CAAC,MAAM,EAAE;IAC9C,QAAQ,EAAE,YAAY,CAAC,QAAQ,KAAK,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,YAAY,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,yCAAyC;CACpI,CAAC,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polen",
-  "version": "0.9.0-next.5",
+  "version": "0.9.0-next.7",
   "type": "module",
   "description": "A framework for delightful GraphQL developer portals",
   "author": {
@@ -84,6 +84,9 @@
     "@radix-ui/themes": "^3.2.1",
     "@rolldown/pluginutils": "1.0.0-beta.12",
     "@rollup/pluginutils": "^5.1.4",
+    "@shikijs/rehype": "^3.6.0",
+    "@shikijs/transformers": "^3.6.0",
+    "@shikijs/twoslash": "^3.6.0",
     "@swc/core": "^1.11.31",
     "@types/jsesc": "^3.0.3",
     "@vitejs/plugin-react": "^4.5.1",
@@ -105,16 +108,21 @@
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
     "react-router": "^7.6.2",
+    "rehype-stringify": "^10.0.1",
     "remark": "^15.0.1",
     "remark-gfm": "^4.0.1",
     "remark-html": "^16.0.1",
+    "remark-parse": "^11.0.0",
+    "remark-rehype": "^11.1.2",
     "resolve.imports": "^2.0.3",
     "rolldown": "1.0.0-beta.12",
+    "shiki": "^3.6.0",
     "source-map": "^0.7.4",
     "superjson": "^2.2.2",
     "tinyglobby": "^0.2.14",
     "tsx": "^4.19.4",
     "typescript": "^5.8.3",
+    "unified": "^11.0.5",
     "vfile": "^6.0.3",
     "vite": "npm:rolldown-vite@~6.3.18",
     "vite-plugin-inspect": "^11.1.0",
@@ -170,6 +178,7 @@
     "test:unit": "vitest",
     "dev": "pnpm build:watch:emit",
     "dev:pokemon": "pnpm polen dev --project examples/pokemon",
+    "build:demos": "zx ./scripts/build-demos.mjs",
     "build:clean": "pnpm tsc --build tsconfig.build.json --clean && rm -rf build",
     "build": "tsc --build tsconfig.build.json",
     "build:watch": "tsc --build tsconfig.build.json --watch",

package/src/api/builder/builder.ts

@@ -12,6 +12,7 @@ const buildDefaults = {
 interface BuildConfigInput {
   debug?: boolean
   architecture?: Config.BuildArchitecture
+  base?: string
 }
 
 export const build = async (buildConfigInput: BuildConfigInput) => {
@@ -22,6 +23,7 @@ export const build = async (buildConfigInput: BuildConfigInput) => {
     overrides: {
       build: {
         architecture: buildConfig.architecture,
+        ...(buildConfig.base ? { base: buildConfig.base } : {}),
       },
       advanced: {
         debug: buildConfig.debug,

package/src/api/config/configurator.ts

@@ -24,7 +24,7 @@ export interface ConfigInput {
    *
    * Relative paths will be resolved relative to this config file.
    *
-   * @defaultValue The directory where the config file is located.
+   * @default The directory where the config file is located.
    */
   root?: string
   /**
@@ -32,7 +32,7 @@ export interface ConfigInput {
    *
    * Powered by [Vite Inspect](https://github.com/antfu-collective/vite-plugin-inspect).
    *
-   * @defaultValue true
+   * @default true
    */
   schema?: SchemaConfigInput
   schemaAugmentations?: SchemaAugmentation.Augmentation[]
@@ -42,12 +42,27 @@ export interface ConfigInput {
      *
      * Used in the navigation bar and in the title tag.
      *
-     * @defaultValue `My Developer Portal`
+     * @default `My Developer Portal`
      */
     title?: string
   }
   build?: {
     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
+     *
+     * Must start and end with `/`.
+     *
+     * @default `/`
+     */
+    base?: string
   }
   advanced?: {
     explorer?: boolean
@@ -64,7 +79,7 @@ export interface ConfigInput {
      * - Global CLI usage against ephemeral projects e.g. a directory with just a
      *   GraphQL Schema file.
      *
-     * @defaultValue false
+     * @default false
      */
     isSelfContainedMode?: boolean
     /**
@@ -90,7 +105,7 @@ export interface ConfigInput {
      *
      * - build output is NOT minified.
      *
-     * @defaultValue false
+     * @default false
      */
     debug?: boolean
     /**
@@ -140,6 +155,7 @@ export interface Config {
   _input: ConfigInput
   build: {
     architecture: BuildArchitecture
+    base: string
   }
   watch: {
     also: string[]
@@ -193,6 +209,7 @@ const configInputDefaults: Config = {
   },
   build: {
     architecture: BuildArchitecture.enum.ssg,
+    base: `/`,
   },
   schema: null,
   ssr: {
@@ -231,6 +248,18 @@ export const normalizeInput = async (
     config.build.architecture = configInput.build.architecture
   }
 
+  if (configInput?.build?.base !== undefined) {
+    // Validate base path
+    const base = configInput.build.base
+    if (!base.startsWith(`/`)) {
+      throw new Error(`Base path must start with "/". Provided: ${base}`)
+    }
+    if (!base.endsWith(`/`)) {
+      throw new Error(`Base path must end with "/". Provided: ${base}`)
+    }
+    config.build.base = base
+  }
+
   if (configInput?.advanced?.debug !== undefined) {
     config.advanced.debug = configInput.advanced.debug
   }

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

@@ -21,7 +21,7 @@ export const fromMemory = async (
   /**
    * Refer to `baseRootDirPath` parameter on {@link normalizeInput}.
    *
-   * @defaultValue `process.cwd()`
+   * @default `process.cwd()`
    */
   baseRootDirPath?: string,
 ) => {

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

@@ -9,6 +9,7 @@ export const toViteUserConfig = (
   config: Config,
 ): ViteUserConfigWithPolen => {
   const viteUserConfigFromPolen: Vite.UserConfig = {
+    base: config.build.base,
     plugins: [Main(config)],
   }
 

package/src/api/schema/read.ts

@@ -6,7 +6,7 @@ export type DataSourceType = `file` | `directory` | `memory` | `data`
 
 export interface Config {
   /**
-   * @defaultValue `true`
+   * @default `true`
    */
   enabled?: boolean
   useDataSources?: Arr.Maybe<DataSourceType>

package/src/api/singletons/markdown/markdown.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, test } from 'vitest'
+import { parse } from './markdown.js'
+
+describe(`markdown parser with syntax highlighting`, () => {
+  test(`parse highlights code blocks`, async () => {
+    const markdown = `
+# Hello
+
+\`\`\`javascript
+const x = 42
+console.log(x)
+\`\`\`
+`
+    const result = await parse(markdown)
+
+    expect(result).toContain(`<h1>Hello</h1>`)
+    expect(result).toContain(`<pre`)
+    expect(result).toContain(`shiki`)
+    expect(result).toContain(`console`)
+    expect(result).toContain(`42`)
+  })
+
+  // Note: parseSync cannot be used with async rehype plugins like Shiki
+  // This is a known limitation - syntax highlighting requires async processing
+
+  test(`parse supports GraphQL syntax`, async () => {
+    const markdown = `
+\`\`\`graphql
+type Query {
+  user(id: ID!): User
+}
+\`\`\`
+`
+    const result = await parse(markdown)
+
+    expect(result).toContain(`type`)
+    expect(result).toContain(`Query`)
+    // Check that both ID and ! are present (they may be in separate spans)
+    expect(result).toContain(`> ID<`)
+    expect(result).toContain(`>!</`)
+  })
+
+  test(`parse handles inline code`, async () => {
+    const markdown = `This is \`inline code\` in a sentence.`
+    const result = await parse(markdown)
+
+    expect(result).toContain(`<code>inline code</code>`)
+  })
+
+  test(`parse supports GitHub Flavored Markdown`, async () => {
+    const markdown = `
+| Column 1 | Column 2 |
+|----------|----------|
+| Cell 1   | Cell 2   |
+
+- [x] Task 1
+- [ ] Task 2
+`
+    const result = await parse(markdown)
+
+    expect(result).toContain(`<table>`)
+    expect(result).toContain(`<input`)
+    expect(result).toContain(`checked`)
+  })
+
+  test(`parse handles code blocks without language`, async () => {
+    const markdown = `
+\`\`\`
+plain text without language
+\`\`\`
+`
+    const result = await parse(markdown)
+
+    expect(result).toContain(`<pre`)
+    expect(result).toContain(`plain text without language`)
+  })
+
+  test(`parse preserves theme CSS variables`, async () => {
+    const markdown = `
+\`\`\`javascript
+const theme = "light"
+\`\`\`
+`
+    const result = await parse(markdown)
+
+    expect(result).toContain(`--shiki-light`)
+    expect(result).toContain(`--shiki-dark`)
+  })
+})

package/src/api/singletons/markdown/markdown.ts

@@ -1,21 +1,43 @@
-import * as Remark from 'remark'
-import RemarkGfm from 'remark-gfm'
-import RemarkHtml from 'remark-html'
+import rehypeShiki from '@shikijs/rehype'
+import rehypeStringify from 'rehype-stringify'
+import remarkGfm from 'remark-gfm'
+import remarkParse from 'remark-parse'
+import remarkRehype from 'remark-rehype'
+import { unified } from 'unified'
 
-export const parse = async (content: string): Promise<string> => {
-  const result = await Remark.remark()
-    .use(RemarkGfm)
-    .use(RemarkHtml)
-    .process(content)
+// Create a processor with Shiki for syntax highlighting (async only)
+const createProcessorWithShiki = () => {
+  return unified()
+    .use(remarkParse)
+    .use(remarkGfm)
+    .use(remarkRehype)
+    .use(rehypeShiki, {
+      themes: {
+        light: `github-light`,
+        dark: `tokyo-night`,
+      },
+      defaultColor: false,
+      cssVariablePrefix: `--shiki-`,
+    })
+    .use(rehypeStringify)
+}
+
+// Create a processor without syntax highlighting for sync processing
+const createProcessorSync = () => {
+  return unified()
+    .use(remarkParse)
+    .use(remarkGfm)
+    .use(remarkRehype)
+    .use(rehypeStringify)
+}
 
+export const parse = async (content: string): Promise<string> => {
+  const result = await createProcessorWithShiki().process(content)
   return String(result)
 }
 
 export const parseSync = (content: string): string => {
-  const result = Remark.remark()
-    .use(RemarkGfm)
-    .use(RemarkHtml)
-    .processSync(content)
-
+  // Note: Syntax highlighting is not available in sync mode due to @shikijs/rehype being async-only
+  const result = createProcessorSync().processSync(content)
   return String(result)
 }

package/src/api/utils/asset-url/asset-url.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, test } from 'vitest'
+import { assetUrl, faviconUrl, joinPaths, pageUrl } from './asset-url.js'
+
+describe('asset-url helpers', () => {
+  describe('joinPaths', () => {
+    test('joins base path with asset path', () => {
+      expect(joinPaths('/', 'assets/style.css')).toBe('/assets/style.css')
+      expect(joinPaths('/my-app/', 'assets/style.css')).toBe('/my-app/assets/style.css')
+      expect(joinPaths('/my-app/', '/assets/style.css')).toBe('/my-app/assets/style.css')
+    })
+
+    test('handles trailing slash in base', () => {
+      expect(joinPaths('/base/', 'path')).toBe('/base/path')
+    })
+
+    test('handles leading slash in path', () => {
+      expect(joinPaths('/base/', '/path')).toBe('/base/path')
+    })
+  })
+
+  describe('assetUrl', () => {
+    test('creates asset URLs with base path', () => {
+      expect(assetUrl('assets/app.js', '/')).toBe('/assets/app.js')
+      expect(assetUrl('assets/app.js', '/my-app/')).toBe('/my-app/assets/app.js')
+      expect(assetUrl('/assets/app.js', '/my-app/')).toBe('/my-app/assets/app.js')
+    })
+  })
+
+  describe('faviconUrl', () => {
+    test('creates favicon URLs with base path', () => {
+      expect(faviconUrl('logo.ico', '/')).toBe('/logo.ico')
+      expect(faviconUrl('logo.ico', '/my-app/')).toBe('/my-app/logo.ico')
+      expect(faviconUrl('/logo.ico', '/my-app/')).toBe('/my-app/logo.ico')
+    })
+  })
+
+  describe('pageUrl', () => {
+    test('creates page URLs with base path', () => {
+      expect(pageUrl('/', '/')).toBe('/')
+      expect(pageUrl('', '/')).toBe('/')
+      expect(pageUrl('/', '/my-app/')).toBe('/my-app/')
+      expect(pageUrl('', '/my-app/')).toBe('/my-app/')
+      expect(pageUrl('about', '/my-app/')).toBe('/my-app/about')
+      expect(pageUrl('/about', '/my-app/')).toBe('/my-app/about')
+    })
+  })
+})

package/src/api/utils/asset-url/asset-url.ts

@@ -0,0 +1,38 @@
+/**
+ * Helper functions for generating asset URLs that respect the base path configuration.
+ */
+
+/**
+ * Join a base path with an asset path, handling leading/trailing slashes correctly.
+ */
+export const joinPaths = (base: string, path: string): string => {
+  // Remove leading slash from path if present
+  const cleanPath = path.startsWith(`/`) ? path.slice(1) : path
+  // Base already has trailing slash by validation
+  return base + cleanPath
+}
+
+/**
+ * Create an asset URL from a path, respecting the base configuration.
+ */
+export const assetUrl = (path: string, base: string): string => {
+  return joinPaths(base, path)
+}
+
+/**
+ * Create a favicon URL from a path, respecting the base configuration.
+ */
+export const faviconUrl = (path: string, base: string): string => {
+  return assetUrl(path, base)
+}
+
+/**
+ * Create a page URL from a path, respecting the base configuration.
+ */
+export const pageUrl = (path: string, base: string): string => {
+  // For pages, we want to ensure no double slashes
+  if (path === `/` || path === ``) {
+    return base
+  }
+  return joinPaths(base, path)
+}

package/src/api/utils/asset-url/index.ts

@@ -0,0 +1 @@
+export * from './asset-url.ts'

package/src/api/vite/plugins/core.ts

@@ -190,9 +190,13 @@ export const Core = (config: Config.Config): Vite.PluginOption[] => {
             const schemaNavbar = navbarData.get('schema')
             schemaNavbar.length = 0 // Clear existing
             if (schema) {
-              schemaNavbar.push({ pathExp: `reference`, title: `Reference` })
+              // 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.
+              schemaNavbar.push({ pathExp: `/reference`, title: `Reference` })
               if (schema.versions.length > 1) {
-                schemaNavbar.push({ pathExp: `changelog`, title: `Changelog` })
+                schemaNavbar.push({ pathExp: `/changelog`, title: `Changelog` })
               }
             }
 
@@ -203,6 +207,7 @@ export const Core = (config: Config.Config): Vite.PluginOption[] => {
             const projectData: ProjectData = {
               schema,
               faviconPath: `/logo.svg`,
+              basePath: config.build.base,
               paths: config.paths.project,
               server: {
                 static: {
@@ -210,8 +215,9 @@ export const Core = (config: Config.Config): Vite.PluginOption[] => {
                   // relative from CWD of process that boots n1ode server
                   // can easily break! Use path relative in server??
                   directory: `./` + config.paths.project.relative.build.root,
-                  // Uses Hono route syntax.
-                  route: `/` + config.paths.project.relative.build.relative.assets + `/*`,
+                  // Uses Hono route syntax - includes base path
+                  route: config.build.base.slice(0, -1) + `/` + config.paths.project.relative.build.relative.assets
+                    + `/*`,
                 },
               },
             }

package/src/api/vite/plugins/pages.ts

@@ -8,6 +8,7 @@ import { Tree } from '#lib/tree/index'
 import { debug } from '#singletons/debug'
 import { superjson } from '#singletons/superjson'
 import mdx from '@mdx-js/rollup'
+import rehypeShiki from '@shikijs/rehype'
 import { Path, Str } from '@wollybeard/kit'
 import remarkGfm from 'remark-gfm'
 
@@ -123,6 +124,22 @@ export const Pages = ({
       ...mdx({
         jsxImportSource: `polen/react`,
         remarkPlugins: [remarkGfm],
+        rehypePlugins: [
+          [
+            rehypeShiki,
+            {
+              themes: {
+                light: `github-light`,
+                dark: `tokyo-night`,
+              },
+              defaultColor: false,
+              cssVariablePrefix: `--shiki-`,
+              transformers: [
+                // Line numbers will be handled via CSS
+              ],
+            },
+          ],
+        ],
       }),
     },
 
@@ -240,7 +257,11 @@ export const Pages = ({
                   const pathExp = FileRouter.pathToExpression([child.value.name])
                   const title = Str.titlizeSlug(child.value.name)
                   navbarPages.push({
-                    pathExp: pathExp.startsWith('/') ? pathExp.slice(1) : pathExp,
+                    // 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.
+                    pathExp: pathExp.startsWith('/') ? pathExp : '/' + pathExp,
                     title,
                   })
                 }
@@ -248,7 +269,11 @@ export const Pages = ({
                 const pathExp = FileRouter.pathToExpression([child.value.name])
                 const title = Str.titlizeSlug(child.value.name)
                 navbarPages.push({
-                  pathExp: pathExp.startsWith('/') ? pathExp.slice(1) : pathExp,
+                  // 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.
+                  pathExp: pathExp.startsWith('/') ? pathExp : '/' + pathExp,
                   title,
                 })
               }

package/src/cli/commands/build.ts

@@ -11,6 +11,10 @@ const args = Command.create()
     `--architecture -a`,
     Api.Config.BuildArchitecture.default('ssg').describe('Which kind of application architecture to output.'),
   )
+  .parameter(
+    `--base -b`,
+    z.string().optional().describe('Base public path for deployment (e.g., /my-project/)'),
+  )
   .settings({
     parameters: {
       environment: {
@@ -33,4 +37,5 @@ const args = Command.create()
 await Api.Builder.build({
   ...(args.debug === false ? {} : { debug: args.debug }),
   ...(args.architecture === 'ssg' ? {} : { architecture: args.architecture }),
+  ...(args.base ? { base: args.base } : {}),
 })

package/src/cli/commands/dev.ts

@@ -14,6 +14,10 @@ const args = Command.create()
     // @ts-expect-error
     z.string().optional().describe(`The path to the project directory. Default is CWD (current working directory).`),
   )
+  .parameter(
+    `--base -b`,
+    z.string().optional().describe('Base public path for deployment (e.g., /my-project/)'),
+  )
   .settings({
     parameters: {
       environment: {
@@ -32,6 +36,7 @@ const dir = ensureOptionalAbsoluteWithCwd(args.project) as string
 const viteUserConfig = await Api.ConfigResolver.fromFile({
   dir,
   overrides: {
+    ...(args.base ? { build: { base: args.base } } : {}),
     advanced: {
       debug: args.debug,
     },

package/src/lib/shiki/index.ts

@@ -0,0 +1 @@
+export * from './shiki.ts'