vike-ripple 0.1.0 → 0.2.1

package/package.json

@@ -1,15 +1,23 @@
 {
   "name": "vike-ripple",
-  "version": "0.1.0",
-  "description": "Vike (vike.dev) integration for Ripple TS — SSR, CSR, streaming, head management",
+  "version": "0.2.1",
+  "description": "Vike extension for Ripple TS — full parity with vike-react/vike-solid/vike-vue",
   "type": "module",
-  "main": "./src/index.js",
+  "types": "./src/types/Config.ts",
   "exports": {
     ".": "./src/index.js",
-    "./setup": "./src/setup.js"
+    "./config": "./src/+config.js",
+    "./setup": "./src/setup.js",
+    "./Head": "./src/components/Head/Head-server.js",
+    "./ClientOnly": "./src/components/ClientOnly.js",
+    "./usePageContext": "./src/hooks/usePageContext.js",
+    "./useData": "./src/hooks/useData.js",
+    "./useConfig": "./src/hooks/useConfig.js",
+    "./src/integration/onRenderHtml.js": "./src/integration/onRenderHtml.js",
+    "./src/integration/onRenderClient.js": "./src/integration/onRenderClient.js"
   },
   "bin": {
-    "vike-ripple": "src/setup.js"
+    "vike-ripple": "./src/setup.js"
   },
   "files": [
     "src"
@@ -27,4 +35,4 @@
     "@ripple-ts/vite-plugin": ">=0.3.0",
     "ripple": ">=0.1.0"
   }
-}
+}

package/src/+config.js

@@ -0,0 +1,40 @@
+import { ssrEffect } from './integration/ssrEffect.js'
+
+/** @type {import('vike/types').Config} */
+const config = {
+  name: 'vike-ripple',
+  require: { vike: '>=0.4.250' },
+
+  onRenderHtml: 'import:vike-ripple/src/integration/onRenderHtml.js:onRenderHtml',
+  onRenderClient: 'import:vike-ripple/src/integration/onRenderClient.js:onRenderClient',
+
+  clientRouting: true,
+  hydrationCanBeAborted: true,
+
+  passToClient: ['_configViaHook'],
+
+  meta: {
+    Head: { env: { server: true }, cumulative: true },
+    Layout: { env: { server: true, client: true }, cumulative: true },
+    title: { env: { server: true, client: true } },
+    description: { env: { server: true } },
+    image: { env: { server: true } },
+    viewport: { env: { server: true } },
+    favicon: { env: { server: true }, global: true },
+    lang: { env: { server: true, client: true } },
+    ssr: { env: { config: true }, effect: ssrEffect },
+    stream: { env: { server: true }, cumulative: true },
+    onBeforeRenderHtml: { env: { server: true }, cumulative: true },
+    onAfterRenderHtml: { env: { server: true }, cumulative: true },
+    onBeforeRenderClient: { env: { server: false, client: true }, cumulative: true },
+    onAfterRenderClient: { env: { server: false, client: true }, cumulative: true },
+    bodyHtmlBegin: { env: { server: true }, cumulative: true, global: true },
+    bodyHtmlEnd: { env: { server: true }, cumulative: true, global: true },
+    headHtmlBegin: { env: { server: true }, cumulative: true, global: true },
+    headHtmlEnd: { env: { server: true }, cumulative: true, global: true },
+    htmlAttributes: { env: { server: true }, global: true, cumulative: true },
+    bodyAttributes: { env: { server: true }, global: true, cumulative: true },
+  },
+}
+
+export default config

package/src/components/ClientOnly.js

@@ -0,0 +1,5 @@
+export { ClientOnly }
+
+function ClientOnly({ children }) {
+  return children
+}

package/src/components/Config/Config-client.js

@@ -0,0 +1,3 @@
+export function Config() {
+  return null
+}

package/src/components/Config/Config-server.js

@@ -0,0 +1,6 @@
+import { useConfig } from '../hooks/useConfig.js'
+
+export function Config(values) {
+  useConfig()(values)
+  return null
+}

package/src/components/Head/Head-client.js

@@ -0,0 +1,3 @@
+export function Head() {
+  return null
+}

package/src/components/Head/Head-server.js

@@ -0,0 +1,7 @@
+import { useConfig } from '../hooks/useConfig.js'
+
+export function Head({ children }) {
+  const config = useConfig()
+  config({ Head: children })
+  return null
+}

package/src/hooks/useConfig.js

@@ -0,0 +1,14 @@
+import { useConfig } from '../hooks/useConfig.js'
+
+export function useConfig() {
+  const pageContext = typeof window !== 'undefined'
+    ? window.__vike_pageContext
+    : globalThis.__vike_pageContext
+
+  return (values) => {
+    if (!pageContext._configViaHook) {
+      pageContext._configViaHook = {}
+    }
+    Object.assign(pageContext._configViaHook, values)
+  }
+}

package/src/hooks/useData.js

@@ -0,0 +1,6 @@
+import { usePageContext } from './usePageContext.js'
+
+export function useData() {
+  const pageContext = usePageContext()
+  return pageContext?.data
+}

package/src/hooks/usePageContext.js

@@ -0,0 +1,6 @@
+export function usePageContext() {
+  const pageContext = typeof window !== 'undefined'
+    ? window.__vike_pageContext
+    : globalThis.__vike_pageContext
+  return pageContext
+}

package/src/index.js

@@ -1,13 +1,23 @@
 /**
- * @vike-ripple/vike-ripple — Vike integration for Ripple TS.
+ * vike-ripple — Vike extension for Ripple TS.
  *
  * ## Setup
- * Run once:  npx vike-ripple setup
- * Or add to package.json:  "postinstall": "vike-ripple setup"
+ * 1. Import config in your renderer/+config.ts:
+ *    import vikeRipple from 'vike-ripple/config'
  *
- * Then add the Vite plugin to vite.config.ts:
- *   import vikeRipple from '@vike-ripple/vike-ripple'
- *   // in plugins: vikeRipple(),
+ * 2. Run setup (once):
+ *    npx vike-ripple setup
+ *
+ * 3. Add optimizeDeps to vite.config.ts:
+ *    optimizeDeps: { exclude: ['ripple'] }
+ *
+ * ## Usage
+ * - +Head.tsrx — inject <head> content
+ * - +Layout.tsrx — layout components
+ * - +title.ts — per-page title
+ * - +description.ts — per-page description
+ * - +ssr.ts — per-page SSR toggle
+ * - +stream.ts — per-page streaming toggle
  */
 export default function vikeRipple() {
   return {

package/src/integration/applyHeadSettings.js

@@ -0,0 +1,10 @@
+export function applyHeadSettings(headList, target) {
+  if (!headList || !Array.isArray(headList)) return
+  for (const head of headList) {
+    if (typeof head === 'string') {
+      target.insertAdjacentHTML('beforeend', head)
+    } else if (head instanceof Node) {
+      target.appendChild(head.cloneNode(true))
+    }
+  }
+}

package/src/integration/getHeadSetting.js

@@ -0,0 +1,7 @@
+export { getHeadSetting }
+
+function getHeadSetting(key, pageContext) {
+  const value = pageContext.config[key]
+  if (value !== undefined && value !== null) return value
+  return pageContext._configViaHook?.[key] ?? null
+}

package/src/integration/getPageElement.js

@@ -0,0 +1,32 @@
+export { getPageElement }
+
+import { getHeadSetting } from './getHeadSetting.js'
+
+function getPageElement(pageContext) {
+  const { Page } = pageContext
+  if (!Page) {
+    return { page: null, pageElement: null }
+  }
+
+  const Layout = pageContext.config.Layout
+  const Wrapper = pageContext.config.Wrapper
+
+  let page = Page
+
+  if (Layout) {
+    const layouts = Array.isArray(Layout) ? Layout : [Layout]
+    for (let i = layouts.length - 1; i >= 0; i--) {
+      const LayoutComponent = layouts[i]
+      page = function NestedPage(props) { return LayoutComponent({ ...props, children: page }) }
+    }
+  }
+
+  if (Wrapper) {
+    const wrappers = Array.isArray(Wrapper) ? Wrapper : [Wrapper]
+    for (const W of wrappers) {
+      page = function WrappedPage(props) { return W({ ...props, children: page }) }
+    }
+  }
+
+  return { page, pageElement: page }
+}

package/src/integration/onRenderClient.js

@@ -0,0 +1,62 @@
+// https://vike.dev/onRenderClient
+export { onRenderClient }
+
+import { hydrate } from 'ripple'
+import { getHeadSetting } from './getHeadSetting.js'
+import { applyHeadSettings } from './applyHeadSettings.js'
+import { callCumulativeHooks } from '../utils/callCumulativeHooks.js'
+
+let rendered = false
+
+const onRenderClient = async (pageContext) => {
+  await callCumulativeHooks(pageContext.config.onBeforeRenderClient, pageContext)
+
+  const container = document.getElementById('root')
+  if (!container) return
+
+  pageContext._headAlreadySet = pageContext.isHydration
+
+  if (pageContext.isHydration && container.innerHTML !== '') {
+    try {
+      hydratePage(pageContext, container)
+      rendered = true
+    } catch (err) {
+      console.warn('[vike-ripple] hydrate failed, falling back to mount:', err)
+    }
+  }
+
+  if (!rendered) {
+    mountPage(pageContext, container)
+    rendered = true
+  }
+
+  updateHead(pageContext)
+
+  await callCumulativeHooks(pageContext.config.onAfterRenderClient, pageContext)
+}
+
+function hydratePage(pageContext, container) {
+  hydrate(pageContext.Page, { target: container, props: {} })
+}
+
+async function mountPage(pageContext, container) {
+  const { mount } = await import('ripple')
+  mount(pageContext.Page, { target: container, props: {} })
+}
+
+function updateHead(pageContext) {
+  if (pageContext._headAlreadySet) return
+
+  const title = getHeadSetting('title', pageContext)
+  if (title && document.title !== title) {
+    document.title = title
+  }
+
+  const lang = getHeadSetting('lang', pageContext)
+  if (lang) {
+    document.documentElement.lang = lang
+  }
+
+  applyHeadSettings(pageContext.config.Head, document.head)
+  applyHeadSettings(pageContext._configViaHook?.Head, document.head)
+}

package/src/integration/onRenderHtml.js

@@ -0,0 +1,120 @@
+export { onRenderHtml }
+
+import { render, create_ssr_stream } from 'ripple/server'
+import { escapeInject, dangerouslySkipEscape } from 'vike/server'
+
+
+import { getHeadSetting } from './getHeadSetting.js'
+import { callCumulativeHooks } from '../utils/callCumulativeHooks.js'
+import { getTagAttributesString } from '../utils/getTagAttributesString.js'
+
+const onRenderHtml = async (pageContext) => {
+  const pageContext2 = pageContext
+  const { Page } = pageContext2
+  if (!Page) throw new Error('No Page')
+
+  await callCumulativeHooks(pageContext2.config.onBeforeRenderHtml, pageContext2)
+
+  const headHtml = getHeadHtml(pageContext2)
+  const { headHtmlBegin, headHtmlEnd, bodyHtmlBegin, bodyHtmlEnd } = await getHtmlInjections(pageContext2)
+  const { htmlAttributesString, bodyAttributesString } = getTagAttributes(pageContext2)
+  const enableStream = !!(pageContext2.config.stream ?? pageContext2.config.rippleStream)
+
+  if (enableStream) {
+    const rippleStream = create_ssr_stream()
+    render(Page, { stream: rippleStream.sink }).catch(e => {
+      console.error('[ripple] render err:', e?.message)
+    })
+    return escapeInject`<!DOCTYPE html>
+      <html${dangerouslySkipEscape(htmlAttributesString)}>
+        <head>
+          <meta charset="UTF-8" />
+          ${dangerouslySkipEscape(headHtmlBegin)}
+          ${dangerouslySkipEscape(headHtml)}
+          ${dangerouslySkipEscape(headHtmlEnd)}
+        </head>
+        <body${dangerouslySkipEscape(bodyAttributesString)}>
+          ${dangerouslySkipEscape(bodyHtmlBegin)}
+          <div id="root">${rippleStream.stream}</div>
+          ${dangerouslySkipEscape(bodyHtmlEnd)}
+        </body>
+      </html>`
+  }
+
+  const { head, body, css } = await render(Page, {})
+
+  const cssHtml = css?.size
+    ? `<style data-ripple-ssr>${[...css].join('')}<` + `/style>`
+    : ''
+
+  const pageHtml = `<div id="root">${body}${cssHtml}</div>`
+
+  pageContext2.pageHtmlString = body
+  await callCumulativeHooks(pageContext2.config.onAfterRenderHtml, pageContext2)
+
+  return escapeInject`<!DOCTYPE html>
+    <html${dangerouslySkipEscape(htmlAttributesString)}>
+      <head>
+        <meta charset="UTF-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        ${dangerouslySkipEscape(headHtmlBegin)}
+        ${dangerouslySkipEscape(head)}
+        ${dangerouslySkipEscape(cssHtml)}
+        ${dangerouslySkipEscape(headHtml)}
+        ${dangerouslySkipEscape(headHtmlEnd)}
+      </head>
+      <body${dangerouslySkipEscape(bodyAttributesString)}>
+        ${dangerouslySkipEscape(bodyHtmlBegin)}
+        <div id="root">${dangerouslySkipEscape(body)}</div>
+        ${dangerouslySkipEscape(bodyHtmlEnd)}
+      </body>
+    </html>`
+}
+
+function getHeadHtml(pageContext) {
+  const favicon = getHeadSetting('favicon', pageContext)
+  const title = getHeadSetting('title', pageContext)
+  const description = getHeadSetting('description', pageContext)
+  const image = getHeadSetting('image', pageContext)
+
+  const faviconTag = !favicon ? '' : `<link rel="icon" href="${favicon}" />`
+  const titleTags = !title ? '' : `<title>${title}</title><meta property="og:title" content="${title}" />`
+  const descriptionTags = !description
+    ? ''
+    : `<meta name="description" content="${description}" /><meta property="og:description" content="${description}" />`
+  const imageTags = !image
+    ? ''
+    : `<meta property="og:image" content="${image}"><meta name="twitter:card" content="summary_large_image">`
+  const viewportTag = getViewportTag(getHeadSetting('viewport', pageContext))
+  const langAttr = getHeadSetting('lang', pageContext)
+  const headElementsHtml = [
+    ...(pageContext.config.Head ?? []),
+    ...(pageContext._configViaHook?.Head ?? []),
+  ]
+    .filter(Boolean)
+    .map(head => (typeof head === 'function' ? head(pageContext) : head))
+    .join('\n')
+
+  return `${titleTags}${viewportTag}${headElementsHtml}${faviconTag}${descriptionTags}${imageTags}`
+}
+
+export function getViewportTag(viewport) {
+  if (viewport === null || viewport === undefined) return ''
+  if (viewport === 'responsive') return '<meta name="viewport" content="width=device-width, initial-scale=1.0" />'
+  if (typeof viewport === 'number') return `<meta name="viewport" content="width=${viewport}" />`
+  return '<meta name="viewport" content="width=device-width, initial-scale=1.0" />'
+}
+
+function getTagAttributes(pageContext) {
+  const htmlAttributesString = getTagAttributesString(pageContext.config.htmlAttributes)
+  const bodyAttributesString = getTagAttributesString(pageContext.config.bodyAttributes)
+  return { htmlAttributesString, bodyAttributesString }
+}
+
+async function getHtmlInjections(pageContext) {
+  const headHtmlBegin = (pageContext.config.headHtmlBegin ?? []).join('\n')
+  const headHtmlEnd = (pageContext.config.headHtmlEnd ?? []).join('\n')
+  const bodyHtmlBegin = (pageContext.config.bodyHtmlBegin ?? []).join('\n')
+  const bodyHtmlEnd = (pageContext.config.bodyHtmlEnd ?? []).join('\n')
+  return { headHtmlBegin, headHtmlEnd, bodyHtmlBegin, bodyHtmlEnd }
+}

package/src/integration/ssrEffect.js

@@ -0,0 +1,15 @@
+export { ssrEffect }
+
+function ssrEffect({ configDefinedAt, configValue }) {
+  if (typeof configValue !== 'boolean') throw new Error(`${configDefinedAt} should be a boolean`)
+  return {
+    meta: {
+      Page: {
+        env: {
+          client: true,
+          server: configValue !== false,
+        },
+      },
+    },
+  }
+}

package/src/setup.js

@@ -1,16 +1,9 @@
-#!/usr/bin/env node
-/**
- * vike-ripple setup — patches Vike and Ripple for .tsrx support.
- *
- * Run once:  npx vike-ripple setup
- * Or add to project's package.json:  "postinstall": "vike-ripple setup"
- */
 import { createRequire } from 'module'
-import { join, dirname } from 'path'
+import { join } from 'path'
 import { readFileSync, writeFileSync, existsSync } from 'fs'
 import { fileURLToPath } from 'url'
 
-const __dirname = dirname(fileURLToPath(import.meta.url))
+const __dirname = fileURLToPath(new URL('.', import.meta.url))
 const projectRoot = process.cwd()
 let exitCode = 0
 
@@ -61,7 +54,7 @@ function patchRippleDirect() {
   log('Patched Ripple plugin for ?direct CSS module loading')
 }
 
-// ── Patch 3: @apply support (tailwindcss integration) ──────────
+// ── Patch 3: @apply support via @reference (no HMR loops) ─────
 function patchRippleApply() {
   const target = resolveRipple('src/index.js')
   if (!target) return
@@ -75,13 +68,16 @@ function patchRippleApply() {
     src = src.replace(
       '// TW_PATCH: prepend tailwindcss so @apply works',
       '// TW_PATCH_APPLY: bring tailwindcss into scope for @apply',
+    )
+      "css = '@import \"tailwindcss\";\\n' + css;",
+      "css = '@import \"tailwindcss\" layer(reference);\\n' + css;",
     )
     writeFileSync(target, src, 'utf-8')
-    log('Upgraded @apply patch format')
+    log('Upgraded @apply patch to @reference (prevents HMR loops)')
     return
   }
 
-  // Fresh install — original unpatched code
+  // Fresh install — prepend @reference comment + tailwind for HMR safety
   const orig = (
     '\t\t\t\t\tif (css) {\n' +
     '\t\t\t\t\t\tconst cssId = createVirtualImportId(filename, root, \'style\');\n' +
@@ -90,7 +86,7 @@ function patchRippleApply() {
   const patched = (
     '\t\t\t\t\tif (css) {\n' +
     '\t\t\t\t\t\t// TW_PATCH_APPLY: bring tailwindcss into scope for @apply\n' +
-    "\t\t\t\t\t\tcss = '@import \"tailwindcss\";\\n' + css;\n" +
+    "\t\t\t\t\t\tcss = '@import \"tailwindcss\" layer(reference);\\n' + css;\n" +
     '\t\t\t\t\t\tconst cssId = createVirtualImportId(filename, root, \'style\');\n' +
     '\t\t\t\t\t\tcssCache.set(cssId, css);'
   )
@@ -98,7 +94,7 @@ function patchRippleApply() {
   const result = src.replace(orig, patched)
   if (result === src) { warn('Could not patch Ripple plugin for @apply'); return }
   writeFileSync(target, result, 'utf-8')
-  log('Patched Ripple plugin for @apply support in <style> blocks')
+  log('Patched Ripple plugin for @apply support in <style> blocks (HMR-safe)')
 }
 
 // ── Resolve helpers ────────────────────────────────────────────

package/src/types/Config.ts

@@ -0,0 +1,33 @@
+import 'vike/types'
+
+declare global {
+  namespace Vike {
+    interface Config {
+      Head?: unknown[]
+      Layout?: unknown[]
+      title?: string | null
+      description?: string | null
+      image?: string | null
+      viewport?: 'responsive' | number | null
+      favicon?: string | null
+      lang?: string | null
+      ssr?: boolean
+      stream?: boolean
+      rippleStream?: boolean
+      Wrapper?: unknown[]
+      Loading?: unknown
+      onBeforeRenderHtml?: ((pageContext: unknown) => void | Promise<void>)[]
+      onAfterRenderHtml?: ((pageContext: unknown) => void | Promise<void>)[]
+      onBeforeRenderClient?: ((pageContext: unknown) => void | Promise<void>)[]
+      onAfterRenderClient?: ((pageContext: unknown) => void | Promise<void>)[]
+      bodyHtmlBegin?: string[]
+      bodyHtmlEnd?: string[]
+      headHtmlBegin?: string[]
+      headHtmlEnd?: string[]
+      htmlAttributes?: Record<string, string | boolean>
+      bodyAttributes?: Record<string, string | boolean>
+    }
+  }
+}
+
+export type __FakeExport_Config = true

package/src/types/PageContext.ts

@@ -0,0 +1,13 @@
+import 'vike/types'
+
+declare global {
+  namespace Vike {
+    interface PageContext {
+      _configViaHook?: Record<string, unknown>
+      _headAlreadySet?: boolean
+      pageHtmlString?: string
+    }
+  }
+}
+
+export type __FakeExport_PageContext = true

package/src/utils/callCumulativeHooks.js

@@ -0,0 +1,11 @@
+export async function callCumulativeHooks(hooks, ...args) {
+  if (!hooks || !Array.isArray(hooks)) return
+  for (const hook of hooks) {
+    if (typeof hook === 'function') {
+      const result = hook(...args)
+      if (result && typeof result.then === 'function') {
+        await result
+      }
+    }
+  }
+}

package/src/utils/getTagAttributesString.js

@@ -0,0 +1,10 @@
+export function getTagAttributesString(attributes) {
+  if (!attributes) return ''
+  return Object.entries(attributes)
+    .map(([key, value]) => {
+      if (value === true) return ` ${key}`
+      if (value === false || value === null || value === undefined) return ''
+      return ` ${key}="${String(value).replace(/"/g, '"')}"`
+    })
+    .join('')
+}

package/src/renderer/+config.ts

@@ -1,10 +0,0 @@
-import type { Config } from 'vike/types'
-
-export default {
-  prerender: false,
-  meta: {
-    rippleStream: {
-      env: { server: true },
-    },
-  },
-} satisfies Config

package/src/renderer/+onRenderClient.tsx

@@ -1,29 +0,0 @@
-// https://vike.dev/onRenderClient
-export { onRenderClient }
-
-import { hydrate } from 'ripple'
-
-let rendered = false
-
-const onRenderClient = async (pageContext) => {
-  const { Page } = pageContext
-  if (!Page) return
-
-  const container = document.getElementById('root')
-  if (!container) return
-
-  if (pageContext.isHydration && container.innerHTML !== '') {
-    try {
-      hydrate(Page, { target: container, props: {} })
-      rendered = true
-    } catch (err) {
-      console.warn('[ripple] hydrate failed, falling back to mount:', err)
-    }
-  }
-
-  if (!rendered) {
-    const { mount } = await import('ripple')
-    mount(Page, { target: container, props: {} })
-    rendered = true
-  }
-}

package/src/renderer/+onRenderHtml.tsx

@@ -1,43 +0,0 @@
-// https://vike.dev/onRenderHtml
-export { onRenderHtml }
-
-import { render, create_ssr_stream } from 'ripple/server'
-import { escapeInject, dangerouslySkipEscape } from 'vike/server'
-
-const onRenderHtml = async (pageContext) => {
-  const { Page } = pageContext
-  if (!Page) throw new Error('No Page')
-
-  const enableStream = !!(pageContext.config.rippleStream ?? pageContext.config.stream)
-
-  if (enableStream) {
-    const rippleStream = create_ssr_stream()
-    render(Page, { stream: rippleStream.sink }).catch(e => {
-      console.error('[ripple] render err:', e?.message)
-    })
-    return escapeInject`<!DOCTYPE html>
-      <html>
-        <head><meta charset="UTF-8" /><meta name="viewport" content="width=device-width, initial-scale=1.0" /></head>
-        <body><div id="root">${rippleStream.stream}</div></body>
-      </html>`
-  }
-
-  const { head, body, css } = await render(Page, {})
-
-  const cssHtml = css?.size
-    ? `<style data-ripple-ssr>${[...css].join('')}<` + `/style>`
-    : ''
-
-  return escapeInject`<!DOCTYPE html>
-    <html>
-      <head>
-        <meta charset="UTF-8" />
-        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-        ${dangerouslySkipEscape(head)}
-        ${dangerouslySkipEscape(cssHtml)}
-      </head>
-      <body>
-        <div id="root">${dangerouslySkipEscape(body)}</div>
-      </body>
-    </html>`
-}