@fecommunity/reactpress-theme-starter 1.0.0-beta.0

package/scripts/dev.mjs

@@ -0,0 +1,221 @@
+#!/usr/bin/env node
+/**
+ * Theme dev server with optional remote ReactPress API.
+ *
+ * Examples:
+ *   pnpm dev
+ *   pnpm dev -- --remote-origin api.yoursite.com
+ *   pnpm dev -- --remote-origin https://api.example.com --port 3001
+ */
+import { spawn } from 'node:child_process'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import {
+  applyDevApiOriginsToEnv,
+  normalizeRemoteOrigin,
+  readDevClientApiOrigin,
+  resolveDevApiOrigins,
+  resolveRemoteThemeApiBase,
+} from './remote-dev.mjs'
+import {
+  DEFAULT_LOCAL_API,
+  DEFAULT_THEME_DEV_PORT,
+  resolveThemeApiEnv as resolveProjectApiEnv,
+} from './resolve-api-env.mjs'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const projectRoot = path.resolve(__dirname, '..')
+
+const ERROR_MESSAGES = {
+  REMOTE_DEFAULT_REQUIRED:
+    'remote mode requires a URL: pass --remote-origin or set REACTPRESS_DEV_REMOTE_ORIGIN',
+  INVALID_ORIGIN: 'Invalid API origin — use a hostname or full URL (e.g. api.yoursite.com)',
+}
+
+function parseArgs(argv) {
+  const result = {
+    port: DEFAULT_THEME_DEV_PORT,
+    remoteOrigin: undefined,
+    adminOrigin: undefined,
+    clientOrigin: undefined,
+    passthrough: [],
+  }
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i]
+
+    if (arg === '--remote-origin') {
+      result.remoteOrigin = argv[++i]
+      continue
+    }
+    if (arg.startsWith('--remote-origin=')) {
+      result.remoteOrigin = arg.slice('--remote-origin='.length)
+      continue
+    }
+    if (arg === '--admin-origin') {
+      result.adminOrigin = argv[++i]
+      continue
+    }
+    if (arg.startsWith('--admin-origin=')) {
+      result.adminOrigin = arg.slice('--admin-origin='.length)
+      continue
+    }
+    if (arg === '--client-origin') {
+      result.clientOrigin = argv[++i]
+      continue
+    }
+    if (arg.startsWith('--client-origin=')) {
+      result.clientOrigin = arg.slice('--client-origin='.length)
+      continue
+    }
+    if (arg === '-p' || arg === '--port') {
+      result.port = Number(argv[++i]) || DEFAULT_THEME_DEV_PORT
+      continue
+    }
+    if (arg.startsWith('--port=')) {
+      result.port = Number(arg.slice('--port='.length)) || DEFAULT_THEME_DEV_PORT
+      continue
+    }
+
+    result.passthrough.push(arg)
+  }
+
+  return result
+}
+
+function readLocalApiUrl() {
+  const fromEnv =
+    process.env.REACTPRESS_API_URL?.trim() ||
+    process.env.SERVER_API_URL?.trim() ||
+    DEFAULT_LOCAL_API
+  return fromEnv.replace(/\/$/, '')
+}
+
+function resolveThemeApiEnv(cli) {
+  const hasOriginFlag =
+    cli.remoteOrigin !== undefined ||
+    cli.adminOrigin !== undefined ||
+    cli.clientOrigin !== undefined
+
+  if (hasOriginFlag) {
+    const resolved = resolveDevApiOrigins(projectRoot, {
+      remoteOrigin: cli.remoteOrigin,
+      adminOrigin: cli.adminOrigin,
+      clientOrigin: cli.clientOrigin,
+    })
+
+    if (resolved.error) {
+      console.error(`[dev] ${ERROR_MESSAGES[resolved.error] || resolved.error}`)
+      process.exit(1)
+    }
+
+    if (
+      cli.remoteOrigin !== undefined &&
+      !resolved.remoteDefault &&
+      cli.adminOrigin === undefined &&
+      cli.clientOrigin === undefined
+    ) {
+      console.error('[dev] --remote-origin requires a hostname (e.g. api.yoursite.com)')
+      process.exit(1)
+    }
+
+    applyDevApiOriginsToEnv(resolved)
+
+    const remoteClient =
+      resolved.client ||
+      (cli.remoteOrigin !== undefined && resolved.remoteDefault ? resolved.remoteDefault : null)
+
+    if (remoteClient) {
+      const apiBase = resolveRemoteThemeApiBase(remoteClient)
+      return {
+        serverApiUrl: apiBase,
+        publicApiUrl: apiBase,
+        remoteOrigin: normalizeRemoteOrigin(remoteClient),
+      }
+    }
+  }
+
+  const envClient = readDevClientApiOrigin(projectRoot)
+  if (envClient) {
+    const apiBase = resolveRemoteThemeApiBase(envClient)
+    return {
+      serverApiUrl: apiBase,
+      publicApiUrl: apiBase,
+      remoteOrigin: normalizeRemoteOrigin(envClient),
+    }
+  }
+
+  const local = readLocalApiUrl()
+  const publicApi = process.env.NEXT_PUBLIC_REACTPRESS_API_URL?.trim()?.replace(/\/$/, '') || local
+
+  return {
+    serverApiUrl: local,
+    publicApiUrl: publicApi,
+    remoteOrigin: null,
+  }
+}
+
+function buildChildEnv(apiEnv, port) {
+  const projectEnv = resolveProjectApiEnv()
+  const mockEnabled = process.env.REACTPRESS_MOCK_API === '1'
+  const localMockApi = `http://localhost:${port}/api`
+  const serverApiUrl = mockEnabled ? localMockApi : apiEnv.serverApiUrl
+  const publicApiUrl = mockEnabled ? '/api' : apiEnv.publicApiUrl
+
+  return {
+    ...process.env,
+    INIT_CWD: projectRoot,
+    REACTPRESS_ORIGINAL_CWD: projectRoot,
+    SERVER_API_URL: serverApiUrl,
+    REACTPRESS_API_URL: serverApiUrl,
+    NEXT_PUBLIC_REACTPRESS_API_URL: publicApiUrl,
+    NEXT_PUBLIC_REACTPRESS_ADMIN_URL: projectEnv.NEXT_PUBLIC_REACTPRESS_ADMIN_URL,
+    CLIENT_SITE_URL: projectEnv.CLIENT_SITE_URL,
+    REACTPRESS_MOCK_API: mockEnabled ? '1' : '',
+    NEXT_TELEMETRY_DISABLED: '1',
+  }
+}
+
+function printBanner(apiEnv, port) {
+  const mockEnabled = process.env.REACTPRESS_MOCK_API === '1'
+  console.log('')
+  console.log('  ReactPress Theme Dev')
+  console.log(`  Local:  http://localhost:${port}`)
+  if (mockEnabled) {
+    console.log(`  API:    /api (mock routes, same-origin in browser)`)
+  } else if (apiEnv.remoteOrigin) {
+    console.log(`  API:    ${apiEnv.serverApiUrl} (remote: ${apiEnv.remoteOrigin})`)
+  } else {
+    console.log(`  API:    ${apiEnv.serverApiUrl} (local)`)
+  }
+  console.log('')
+}
+
+function main() {
+  const cli = parseArgs(process.argv.slice(2))
+  const apiEnv = resolveThemeApiEnv(cli)
+  const childEnv = buildChildEnv(apiEnv, cli.port)
+
+  printBanner(apiEnv, cli.port)
+
+  const nextBin = path.join(projectRoot, 'node_modules', 'next', 'dist', 'bin', 'next')
+  const child = spawn(
+    process.execPath,
+    [nextBin, 'dev', '-p', String(cli.port), ...cli.passthrough],
+    {
+      cwd: projectRoot,
+      env: childEnv,
+      stdio: 'inherit',
+    }
+  )
+
+  child.on('exit', (code, signal) => {
+    if (signal) {
+      process.kill(process.pid, signal)
+      return
+    }
+    process.exit(code ?? 0)
+  })
+}
+
+main()

package/scripts/ensure-env.mjs

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+/**
+ * Ensure a `.env` file exists for @fecommunity/reactpress-toolkit/config (requires on-disk env).
+ * Copies from `.env.example` when missing; optionally merges overrides from CI / Vercel / mock build.
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const projectRoot = path.resolve(__dirname, '..')
+
+const MERGE_KEYS = [
+  'REACTPRESS_API_URL',
+  'SERVER_API_URL',
+  'NEXT_PUBLIC_REACTPRESS_API_URL',
+  'CLIENT_SITE_URL',
+  'BASE_PATH',
+  'REACTPRESS_MOCK_API',
+  'NEXT_PUBLIC_REACTPRESS_ADMIN_URL',
+  'REACTPRESS_DEV_REMOTE_ORIGIN',
+]
+
+const FALLBACK_ENV = `# Auto-generated for CI / Vercel mock build
+REACTPRESS_API_URL=http://localhost:3002/api
+NEXT_PUBLIC_REACTPRESS_API_URL=http://localhost:3002/api
+CLIENT_SITE_URL=http://localhost:3001
+`
+
+function readBaseContent(envPath, examplePath) {
+  if (fs.existsSync(envPath)) {
+    return fs.readFileSync(envPath, 'utf8')
+  }
+  if (fs.existsSync(examplePath)) {
+    return fs.readFileSync(examplePath, 'utf8')
+  }
+  return FALLBACK_ENV
+}
+
+function upsertEnvLine(lines, key, value) {
+  const entry = `${key}=${value}`
+  const index = lines.findIndex((line) => {
+    const trimmed = line.trim()
+    return trimmed && !trimmed.startsWith('#') && trimmed.startsWith(`${key}=`)
+  })
+
+  if (index >= 0) {
+    lines[index] = entry
+  } else {
+    lines.push(entry)
+  }
+}
+
+/**
+ * @param {string} [root]
+ * @param {{ onlyIfMissing?: boolean, overrides?: Record<string, string | undefined> }} [options]
+ */
+export function ensureEnvFile(root = projectRoot, options = {}) {
+  const { onlyIfMissing = false, overrides = {} } = options
+  const envPath = path.join(root, '.env')
+  const examplePath = path.join(root, '.env.example')
+
+  if (onlyIfMissing && fs.existsSync(envPath)) {
+    return envPath
+  }
+
+  const lines = readBaseContent(envPath, examplePath)
+    .split('\n')
+    .filter((line, index, all) => !(index === all.length - 1 && line === ''))
+
+  for (const key of MERGE_KEYS) {
+    const override = overrides[key]?.trim()
+    if (override) {
+      upsertEnvLine(lines, key, override)
+      continue
+    }
+
+    if (onlyIfMissing) continue
+
+    const fromProcess = process.env[key]?.trim()
+    if (fromProcess) {
+      upsertEnvLine(lines, key, fromProcess)
+    }
+  }
+
+  const nextContent = `${lines.join('\n').trimEnd()}\n`
+  if (!fs.existsSync(envPath) || fs.readFileSync(envPath, 'utf8') !== nextContent) {
+    fs.writeFileSync(envPath, nextContent)
+    console.log(`[ensure-env] wrote ${envPath}`)
+  }
+
+  return envPath
+}
+
+const isDirectRun =
+  process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+
+if (isDirectRun) {
+  ensureEnvFile(projectRoot, { onlyIfMissing: true })
+}

package/scripts/remote-dev.mjs

@@ -0,0 +1,143 @@
+import fs from 'node:fs'
+import path from 'node:path'
+
+/** Normalize user input (e.g. api.yoursite.com) to an HTTPS origin without trailing slash. */
+export function normalizeRemoteOrigin(input) {
+  const raw = typeof input === 'string' ? input.trim() : ''
+  if (!raw) return null
+
+  let origin = raw
+  if (!/^https?:\/\//i.test(origin)) {
+    origin = `https://${origin}`
+  }
+  return origin.replace(/\/$/, '')
+}
+
+function readEnvValue(projectRoot, key) {
+  const envPath = path.join(projectRoot, '.env')
+  try {
+    const content = fs.readFileSync(envPath, 'utf8')
+    const match = content.match(new RegExp(`^${key}=(.+)$`, 'm'))
+    if (match) {
+      return match[1].trim().replace(/^['"]|['"]$/g, '')
+    }
+  } catch {
+    // ignore
+  }
+  return null
+}
+
+function readOriginFromEnv(projectRoot, envKey) {
+  const fromShell = normalizeRemoteOrigin(process.env[envKey])
+  if (fromShell) return fromShell
+  return normalizeRemoteOrigin(readEnvValue(projectRoot, envKey))
+}
+
+/** Default remote API URL (--remote-origin or REACTPRESS_DEV_REMOTE_ORIGIN). */
+export function readDevRemoteDefault(projectRoot) {
+  return readOriginFromEnv(projectRoot, 'REACTPRESS_DEV_REMOTE_ORIGIN')
+}
+
+/** Remote admin API origin; null = local Nest. */
+export function readDevAdminApiOrigin(projectRoot) {
+  return readOriginFromEnv(projectRoot, 'REACTPRESS_DEV_ADMIN_API_ORIGIN')
+}
+
+/** Remote client/theme API origin (nginx /api); null = local Nest. */
+export function readDevClientApiOrigin(projectRoot) {
+  return readOriginFromEnv(projectRoot, 'REACTPRESS_DEV_CLIENT_API_ORIGIN')
+}
+
+/**
+ * Parse one origin flag: local | remote | URL/host.
+ * @returns {{ url: string|null } | { error: string }}
+ */
+export function parseOriginSpec(value, remoteDefault) {
+  const trimmed = typeof value === 'string' ? value.trim() : ''
+  if (!trimmed) return { url: null }
+
+  const lower = trimmed.toLowerCase()
+  if (lower === 'local') return { url: null }
+  if (lower === 'remote') {
+    if (!remoteDefault) return { error: 'REMOTE_DEFAULT_REQUIRED' }
+    return { url: remoteDefault }
+  }
+
+  const url = normalizeRemoteOrigin(trimmed)
+  if (!url) return { error: 'INVALID_ORIGIN' }
+  return { url }
+}
+
+/**
+ * Resolve admin/client API targets for this dev session.
+ * @returns {{ admin: string|null, client: string|null, remoteDefault: string|null, needsLocalApi: boolean, error?: string }}
+ */
+export function resolveDevApiOrigins(projectRoot, cli = {}) {
+  const remoteDefault = normalizeRemoteOrigin(cli.remoteOrigin) || readDevRemoteDefault(projectRoot)
+
+  const onlyRemoteShorthand =
+    cli.remoteOrigin !== undefined &&
+    cli.adminOrigin === undefined &&
+    cli.clientOrigin === undefined
+
+  const resolveSide = (cliValue, envKey, useRemoteShorthand) => {
+    if (cliValue !== undefined) {
+      return parseOriginSpec(cliValue, remoteDefault)
+    }
+    const fromEnv = readOriginFromEnv(projectRoot, envKey)
+    if (fromEnv) return { url: fromEnv }
+    if (useRemoteShorthand && remoteDefault) return { url: remoteDefault }
+    return { url: null }
+  }
+
+  const adminParsed = resolveSide(
+    cli.adminOrigin,
+    'REACTPRESS_DEV_ADMIN_API_ORIGIN',
+    onlyRemoteShorthand
+  )
+  if (adminParsed.error) return { error: adminParsed.error }
+
+  const clientParsed = resolveSide(
+    cli.clientOrigin,
+    'REACTPRESS_DEV_CLIENT_API_ORIGIN',
+    onlyRemoteShorthand
+  )
+  if (clientParsed.error) return { error: clientParsed.error }
+
+  const admin = adminParsed.url
+  const client = clientParsed.url
+
+  return {
+    admin,
+    client,
+    remoteDefault,
+    needsLocalApi: !admin || !client,
+  }
+}
+
+export function applyDevApiOriginsToEnv(origins) {
+  if (origins.remoteDefault) {
+    process.env.REACTPRESS_DEV_REMOTE_ORIGIN = origins.remoteDefault
+  } else {
+    delete process.env.REACTPRESS_DEV_REMOTE_ORIGIN
+  }
+
+  if (origins.admin) {
+    process.env.REACTPRESS_DEV_ADMIN_API_ORIGIN = origins.admin
+  } else {
+    delete process.env.REACTPRESS_DEV_ADMIN_API_ORIGIN
+  }
+
+  if (origins.client) {
+    process.env.REACTPRESS_DEV_CLIENT_API_ORIGIN = origins.client
+  } else {
+    delete process.env.REACTPRESS_DEV_CLIENT_API_ORIGIN
+  }
+}
+
+/** Nest client base URL (includes /api when origin is host-only). */
+export function resolveRemoteThemeApiBase(origin) {
+  const base = origin.replace(/\/$/, '')
+  if (/\/api$/i.test(base)) return base
+  return `${base}/api`
+}

package/scripts/resolve-api-env.mjs

@@ -0,0 +1,114 @@
+/**
+ * Single source of truth for ReactPress theme URL resolution (build, dev, Vercel).
+ */
+export const DEFAULT_LOCAL_API = 'http://localhost:3002/api'
+export const DEFAULT_LOCAL_SITE = 'http://localhost:3001'
+export const DEFAULT_LOCAL_ADMIN = 'http://localhost:3000'
+export const DEFAULT_THEME_DEV_PORT = 3001
+export const DEFAULT_VERCEL_DEMO_SITE = 'https://reactpress-theme-starter.vercel.app'
+
+function trimUrl(value) {
+  if (typeof value !== 'string') return ''
+  return value.trim().replace(/\/$/, '')
+}
+
+function trimApiUrl(value) {
+  return trimUrl(value)
+}
+
+export function isLocalhostUrl(url) {
+  return /localhost|127\.0\.0\.1/i.test(url)
+}
+
+function toApiBase(origin) {
+  const base = trimApiUrl(origin)
+  if (!base) return ''
+  return /\/api$/i.test(base) ? base : `${base}/api`
+}
+
+function apiOriginFromBase(serverApi) {
+  return serverApi.replace(/\/api\/?$/, '')
+}
+
+/**
+ * @param {NodeJS.ProcessEnv} [processEnv]
+ */
+export function resolveClientSiteUrl(processEnv = process.env) {
+  const explicit = trimUrl(processEnv.CLIENT_SITE_URL)
+  if (explicit) return explicit
+
+  const vercelUrl = trimUrl(processEnv.VERCEL_URL)
+  if (vercelUrl) {
+    return (vercelUrl.startsWith('http') ? vercelUrl : `https://${vercelUrl}`).replace(/\/$/, '')
+  }
+
+  if (processEnv.VERCEL === '1') {
+    return DEFAULT_VERCEL_DEMO_SITE
+  }
+
+  return DEFAULT_LOCAL_SITE
+}
+
+/**
+ * @param {NodeJS.ProcessEnv} [processEnv]
+ */
+export function resolveThemeApiEnv(processEnv = process.env) {
+  const mockEnabled = processEnv.REACTPRESS_MOCK_API === '1'
+  const explicitServer =
+    trimApiUrl(processEnv.REACTPRESS_API_URL) || trimApiUrl(processEnv.SERVER_API_URL)
+  const explicitPublic = trimApiUrl(processEnv.NEXT_PUBLIC_REACTPRESS_API_URL)
+  const remoteApi = toApiBase(processEnv.REACTPRESS_DEV_REMOTE_ORIGIN)
+
+  let serverApi = explicitServer || explicitPublic || remoteApi || DEFAULT_LOCAL_API
+
+  // Vercel runtime: SSR should call this deployment's /api mock route handler.
+  if (mockEnabled && processEnv.VERCEL === '1' && !explicitServer) {
+    serverApi = `${resolveClientSiteUrl(processEnv)}/api`
+  }
+
+  let publicApi = explicitPublic
+  if (mockEnabled) {
+    // Browser must hit same-origin mock routes; ignore .env localhost:3002.
+    publicApi = '/api'
+  } else if (!publicApi) {
+    if (processEnv.NODE_ENV === 'production' && !isLocalhostUrl(serverApi)) {
+      publicApi = '/api'
+    } else {
+      publicApi = serverApi
+    }
+  }
+
+  const nginxEntry = trimUrl(processEnv.REACTPRESS_NGINX_ENTRY_URL || processEnv.NGINX_ENTRY_URL)
+  let adminUrl =
+    trimUrl(processEnv.NEXT_PUBLIC_REACTPRESS_ADMIN_URL) ||
+    (nginxEntry ? `${nginxEntry}/admin` : DEFAULT_LOCAL_ADMIN)
+
+  if (processEnv.VERCEL === '1' && isLocalhostUrl(adminUrl) && !isLocalhostUrl(serverApi)) {
+    adminUrl = `${apiOriginFromBase(serverApi)}/admin`
+  }
+
+  return {
+    SERVER_API_URL: serverApi,
+    REACTPRESS_API_URL: serverApi,
+    NEXT_PUBLIC_REACTPRESS_API_URL: publicApi,
+    NEXT_PUBLIC_REACTPRESS_ADMIN_URL: adminUrl,
+    CLIENT_SITE_URL: resolveClientSiteUrl(processEnv),
+  }
+}
+
+/**
+ * @param {ReturnType<typeof resolveThemeApiEnv>} apiEnv
+ */
+export function resolveApiRewriteOrigin(apiEnv) {
+  return apiOriginFromBase(apiEnv.SERVER_API_URL)
+}
+
+/**
+ * @param {NodeJS.ProcessEnv} [processEnv]
+ */
+export function resolveApiPreconnectOrigin(processEnv = process.env) {
+  const apiEnv = resolveThemeApiEnv(processEnv)
+  const origin = resolveApiRewriteOrigin(apiEnv)
+  if (!origin.startsWith('http') || isLocalhostUrl(origin)) return null
+  return origin
+}

package/scripts/set-publish-version.mjs

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+/**
+ * Set package.json + theme.json version for CI npm publish (does not commit).
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const version = process.argv[2]?.trim()
+
+if (!version || !/^\d+\.\d+\.\d+(-[\w.]+)?$/.test(version)) {
+  console.error('Usage: node scripts/set-publish-version.mjs <semver>')
+  process.exit(1)
+}
+
+const VERSION_RE = /("version"\s*:\s*")[^"]+(")/
+
+function setFileVersion(filePath) {
+  const content = fs.readFileSync(filePath, 'utf8')
+  if (!VERSION_RE.test(content)) {
+    console.error(`Could not find version field in ${filePath}`)
+    process.exit(1)
+  }
+  fs.writeFileSync(filePath, content.replace(VERSION_RE, `$1${version}$2`))
+}
+
+setFileVersion(path.join(root, 'package.json'))
+setFileVersion(path.join(root, 'theme.json'))
+
+console.log(`[set-publish-version] ${version}`)