feat: allow passing props to templates via render()

cossssmin · cossssmin · commit 1b3df37cabe5 · 2026-07-01T16:17:04.000+03:00
diff --git a/src/render/createRenderer.ts b/src/render/createRenderer.ts
@@ -44,7 +44,7 @@ export interface RenderedTemplate {
 }
 
 export interface Renderer {
-  render(input: string | Component, config: MaizzleConfig, opts?: { source?: string }): Promise<RenderedTemplate>
+  render(input: string | Component, config: MaizzleConfig, opts?: { source?: string; props?: Record<string, any> }): Promise<RenderedTemplate>
   invalidate(filePath: string): Promise<void>
   invalidateAll(): Promise<void>
   close(): Promise<void>
@@ -412,7 +412,7 @@ export async function createRenderer(
   const server = await createServer(finalConfig)
 
   return {
-    async render(input: string | Component, config: MaizzleConfig, opts?: { source?: string }): Promise<RenderedTemplate> {
+    async render(input: string | Component, config: MaizzleConfig, opts?: { source?: string; props?: Record<string, any> }): Promise<RenderedTemplate> {
       let component: Component
       let configKey: InjectionKey<MaizzleConfig>
       let contextKey: InjectionKey<RenderContext>
@@ -469,7 +469,7 @@ export async function createRenderer(
       }
 
       const head = createHead({ disableDefaults: true })
-      const app = createSSRApp(component)
+      const app = createSSRApp(component, opts?.props)
       app.use(head)
 
       // Register user Vue plugins, directives, and global properties
diff --git a/src/render/index.ts b/src/render/index.ts
@@ -39,6 +39,7 @@ export async function render(
   }
 
   const resolvedConfig = resolveConfigObject(config)
+  const { props, ...templateConfig } = resolvedConfig
 
   /**
    * Reuse a renderer started by the Vite plugin when one is active.
@@ -59,7 +60,7 @@ export async function render(
       && ['.vue', '.md'].includes(extname(template))
       && !template.includes('\n')
 
-    const rendered = await renderer.render(isFile ? resolve(template) : template, resolvedConfig)
+    const rendered = await renderer.render(isFile ? resolve(template) : template, templateConfig, { props })
     let html = rendered.html
 
     const doctype = rendered.doctype ?? rendered.templateConfig.doctype ?? '<!DOCTYPE html>'
diff --git a/src/tests/render/props.test.ts b/src/tests/render/props.test.ts
@@ -0,0 +1,65 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { rmSync } from 'node:fs'
+import { render } from '../../render/index.ts'
+import { createTempProject } from './_helpers.ts'
+
+describe('render props', () => {
+  let tempDir: string
+  const originalCwd = process.cwd()
+
+  beforeEach(() => {
+    tempDir = createTempProject()
+    process.chdir(tempDir)
+  })
+
+  afterEach(() => {
+    process.chdir(originalCwd)
+    rmSync(tempDir, { recursive: true, force: true })
+  })
+
+  it('passes props to the template via defineProps', async () => {
+    const result = await render(`
+      <script setup>
+      defineProps(['name'])
+      </script>
+      <template>
+        <div>Hello {{ name }}</div>
+      </template>
+    `, {
+      props: { name: 'Ava' },
+    })
+
+    expect(result.html).toContain('Hello Ava')
+  })
+
+  it('does not leak props into useConfig() or the returned config', async () => {
+    const result = await render(`
+      <script setup>
+      const config = useConfig()
+      </script>
+      <template>
+        <div>{{ config.props === undefined ? 'clean' : 'leaked' }}</div>
+      </template>
+    `, {
+      props: { name: 'Ava' },
+    })
+
+    expect(result.html).toContain('clean')
+    expect(result.config.props).toBeUndefined()
+  })
+
+  it('does not render a declared prop as a fallthrough attribute', async () => {
+    const result = await render(`
+      <script setup>
+      defineProps(['name'])
+      </script>
+      <template>
+        <div>{{ name }}</div>
+      </template>
+    `, {
+      props: { name: 'Ava' },
+    })
+
+    expect(result.html).not.toContain('name="Ava"')
+  })
+})
diff --git a/src/types/config.ts b/src/types/config.ts
@@ -744,6 +744,18 @@ export interface MaizzleConfig {
    * }
    */
   vue?: VueConfig
+  /**
+   * Props passed to the template's root component when rendering
+   * programmatically. Map 1:1 to the template's `defineProps`. Not
+   * merged into `useConfig()`.
+   *
+   * Props not declared via `defineProps` fall through as HTML
+   * attributes on the root element, so declare every prop you pass.
+   *
+   * @example
+   * render('./welcome.vue', { props: { name: 'Ava', plan: 'Pro' } })
+   */
+  props?: Record<string, any>
 
   // Events
 
