@lexibase/create-rdx 1.0.0-beta.9 → 1.0.1

package/README.md

@@ -0,0 +1,49 @@
+# @lexibase/create-rdx
+
+Create a documentation project using Next.js, Tailwind CSS and shadcn/ui Base UI.
+
+Requires Node.js 22.18+ (22.x) or 24.11+ (24.x), preferably the latest patch.
+See the repository's SUPPORT.md for the automated platform/package-manager matrix.
+
+## Installation
+
+```sh
+npm create @lexibase/rdx@latest
+# Or: pnpm create @lexibase/rdx@latest
+```
+
+The prompt asks for the project name, which becomes a new directory inside
+the current directory. You can also pass it directly:
+
+```sh
+npm create @lexibase/rdx@latest my-docs
+pnpm create @lexibase/rdx@latest my-docs
+```
+
+Use a short name starting with a letter or number, followed by letters, numbers,
+dots, dashes or underscores. Paths, spaces, trailing dots and Windows/npm reserved
+names are rejected. The folder keeps its capitalization; the npm package name
+is lowercased. Existing paths are never reused or overwritten.
+
+## Options
+
+Forward options after `--` when using npm create:
+
+```sh
+npm create @lexibase/rdx@latest -- --help
+npm create @lexibase/rdx@latest -- --version
+npm create @lexibase/rdx@latest my-docs -- --skip-install
+```
+
+`--skip-install` creates source files without installing dependencies or preparing
+`.rdx/`. Otherwise the creator uses the invoking package manager and prepares
+the runtime. Follow the commands printed by the generator.
+
+## Recovery
+
+If installation or preparation fails, the command exits with an error and keeps
+the generated files. Fix the reported issue, enter the created folder and retry
+installation/development using the same package manager. Do not rerun creation
+over that directory, delete lockfiles or disable security policies automatically.
+
+See the generated README for development, public files and optional versioning.

package/bin/index.js

@@ -7,12 +7,7 @@ import spawn from 'cross-spawn'
 import fs from 'fs-extra'
 import prompts from 'prompts'
 
-const projectNamePattern = /^[a-z0-9][a-z0-9._-]*$/i
-const argumentsFromCli = process.argv.slice(2)
-const skipInstall = argumentsFromCli.includes('--skip-install')
-const nameFromCli = argumentsFromCli.find(
-  (argument) => !argument.startsWith('-')
-)
+import { parseArguments, validateProjectName } from './options.mjs'
 
 function getPackageManager() {
   const userAgent = process.env.npm_config_user_agent || ''
@@ -23,18 +18,6 @@ function getPackageManager() {
   return 'npm'
 }
 
-function validateProjectName(projectName) {
-  if (!projectName) return 'Please enter a project name.'
-  if (!projectNamePattern.test(projectName)) {
-    return 'Use letters, numbers, dots, dashes, or underscores only.'
-  }
-  if (projectName === '.' || projectName === '..') {
-    return 'Choose a name other than . or ...'
-  }
-
-  return true
-}
-
 function run(command, args, cwd) {
   return new Promise((resolve, reject) => {
     // Reuse the Node entry point when available. Otherwise cross-spawn
@@ -59,72 +42,127 @@ function run(command, args, cwd) {
   })
 }
 
-const response = nameFromCli
-  ? { projectName: nameFromCli }
-  : await prompts({
-      type: 'text',
-      name: 'projectName',
-      message: 'What is your project named?',
-      validate: validateProjectName,
-    })
+async function main() {
+  const {
+    projectName: nameFromCli,
+    skipInstall,
+    help,
+    version,
+  } = parseArguments(process.argv.slice(2))
+  if (help) {
+    console.log('Usage: create-rdx [project-name] [--skip-install]')
+    console.log('  Without a project name, RDX asks for one interactively.')
+    console.log(
+      '  --skip-install  Create files without installing dependencies.'
+    )
+    console.log('  --help, -h      Show this help.')
+    console.log('  --version, -v   Show the generator version.')
+    return
+  }
+  if (version) {
+    const pkg = await fs.readJson(new URL('../package.json', import.meta.url))
+    console.log(pkg.version)
+    return
+  }
+  if (nameFromCli !== undefined) {
+    const validation = validateProjectName(nameFromCli)
+    if (validation !== true) throw new Error(validation)
+  }
+  const response =
+    nameFromCli !== undefined
+      ? { projectName: nameFromCli }
+      : await prompts({
+          type: 'text',
+          name: 'projectName',
+          message: 'What is your project named?',
+          validate: validateProjectName,
+        })
+
+  const { projectName } = response
+  if (!projectName) {
+    console.log('Project creation cancelled.')
+    return
+  }
+  const validation = validateProjectName(projectName)
+  if (validation !== true) throw new Error(validation)
 
-const { projectName } = response
-if (!projectName) {
-  console.log('Project creation cancelled.')
-  process.exit(0)
-}
+  const targetDir = path.resolve(process.cwd(), projectName)
+  const relativeTarget = path.relative(process.cwd(), targetDir)
 
-const targetDir = path.resolve(process.cwd(), projectName)
-const relativeTarget = path.relative(process.cwd(), targetDir)
+  if (relativeTarget.startsWith('..') || path.isAbsolute(relativeTarget)) {
+    throw new Error('Project must be created inside the current directory.')
+  }
+  try {
+    await fs.mkdir(targetDir)
+  } catch (error) {
+    if (error.code === 'EEXIST')
+      throw new Error(
+        `The path "${projectName}" already exists. Choose another name; existing files are never overwritten.`
+      )
+    throw error
+  }
 
-if (relativeTarget.startsWith('..') || path.isAbsolute(relativeTarget)) {
-  throw new Error('Project must be created inside the current directory.')
-}
-if (await fs.pathExists(targetDir)) {
-  throw new Error(`The directory "${projectName}" already exists.`)
-}
+  const currentFile = fileURLToPath(import.meta.url)
+  const templateDir = path.resolve(
+    path.dirname(currentFile),
+    '../templates/default'
+  )
+  await fs.copy(templateDir, targetDir, {
+    errorOnExist: true,
+    overwrite: false,
+  })
+  await fs.ensureDir(path.join(targetDir, 'public'))
 
-const currentFile = fileURLToPath(import.meta.url)
-const templateDir = path.resolve(
-  path.dirname(currentFile),
-  '../templates/default'
-)
-await fs.copy(templateDir, targetDir, { errorOnExist: true })
-await fs.ensureDir(path.join(targetDir, 'public'))
-
-const gitignoreTemplatePath = path.join(targetDir, 'gitignore.template')
-await fs.move(gitignoreTemplatePath, path.join(targetDir, '.gitignore'), {
-  overwrite: true,
-})
-await fs.remove(path.join(targetDir, 'gitignore'))
-await fs.remove(path.join(targetDir, '.npmignore'))
-
-const pkgPath = path.join(targetDir, 'package.json')
-const pkg = await fs.readJson(pkgPath)
-pkg.name = projectName
-await fs.writeJson(pkgPath, pkg, { spaces: 2 })
-
-const readmePath = path.join(targetDir, 'README.md')
-const readme = await fs.readFile(readmePath, 'utf8')
-await fs.writeFile(
-  readmePath,
-  readme
-    .replaceAll('{{RDX_PROJECT_NAME}}', projectName)
-    .replaceAll('__RDX_PROJECT_NAME__', projectName)
-)
-
-const packageManager = getPackageManager()
-
-if (!skipInstall) {
-  console.log(`\nInstalling dependencies with ${packageManager}...\n`)
-  await run(packageManager, ['install'], targetDir)
-  const prepareArgs =
-    packageManager === 'npm'
-      ? ['exec', '--', 'rdx', 'prepare']
-      : ['exec', 'rdx', 'prepare']
-  await run(packageManager, prepareArgs, targetDir)
+  const gitignoreTemplatePath = path.join(targetDir, 'gitignore.template')
+  await fs.move(gitignoreTemplatePath, path.join(targetDir, '.gitignore'), {
+    overwrite: true,
+  })
+  await fs.remove(path.join(targetDir, 'gitignore'))
+  await fs.remove(path.join(targetDir, '.npmignore'))
+
+  const pkgPath = path.join(targetDir, 'package.json')
+  const pkg = await fs.readJson(pkgPath)
+  pkg.name = projectName.toLowerCase()
+  await fs.writeJson(pkgPath, pkg, { spaces: 2 })
+
+  const readmePath = path.join(targetDir, 'README.md')
+  const readme = await fs.readFile(readmePath, 'utf8')
+  await fs.writeFile(
+    readmePath,
+    readme
+      .replaceAll('{{RDX_PROJECT_NAME}}', projectName)
+      .replaceAll('__RDX_PROJECT_NAME__', projectName)
+  )
+
+  const packageManager = getPackageManager()
+
+  if (!skipInstall) {
+    try {
+      console.log(`\nInstalling dependencies with ${packageManager}...\n`)
+      await run(packageManager, ['install'], targetDir)
+      const prepareArgs =
+        packageManager === 'npm'
+          ? ['exec', '--', 'rdx', 'prepare']
+          : ['exec', 'rdx', 'prepare']
+      await run(packageManager, prepareArgs, targetDir)
+    } catch (error) {
+      const runner = packageManager === 'npm' ? 'npm run' : packageManager
+      throw new Error(
+        `${error.message}\nProject files were kept in "${projectName}". Fix the reported error, then retry:\n  cd ${projectName}\n  ${packageManager} install\n  ${runner} dev`
+      )
+    }
+  }
+
+  console.log(`\nRDX project "${projectName}" created successfully.\n`)
+  console.log(`  cd ${projectName}`)
+  console.log(
+    `  ${packageManager === 'npm' ? 'npm run' : packageManager} dev\n`
+  )
 }
 
-console.log(`\nRDX project "${projectName}" created successfully.\n`)
-console.log(`  cd ${projectName}`)
-console.log(`  ${packageManager === 'npm' ? 'npm run' : packageManager} dev\n`)
+try {
+  await main()
+} catch (error) {
+  console.error(`[RDX] ${error.message}`)
+  process.exitCode = 1
+}

package/bin/options.mjs

@@ -0,0 +1,30 @@
+export function validateProjectName(name) {
+  if (!name) return 'Please enter a project name.'
+  if (name.length > 214)
+    return 'Use a project name with at most 214 characters.'
+  if (!/^[a-z0-9][a-z0-9._-]*$/i.test(name) || name.endsWith('.'))
+    return 'Start with a letter or number; use only letters, numbers, dots, dashes or underscores, and do not end with a dot.'
+  if (/^(con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(name))
+    return 'Choose a project name that is not reserved by Windows.'
+  if (['node_modules', 'favicon.ico'].includes(name.toLowerCase()))
+    return 'Choose a project name that is not reserved by npm.'
+  return true
+}
+
+export function parseArguments(args) {
+  let projectName
+  let skipInstall = false
+  let help = false
+  let version = false
+  for (const argument of args) {
+    if (argument === '--skip-install') skipInstall = true
+    else if (argument === '--help' || argument === '-h') help = true
+    else if (argument === '--version' || argument === '-v') version = true
+    else if (argument.startsWith('-'))
+      throw new Error(`Unknown option "${argument}". Use --help for usage.`)
+    else if (projectName !== undefined)
+      throw new Error('Provide only one project name. Use --help for usage.')
+    else projectName = argument
+  }
+  return { projectName, skipInstall, help, version }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lexibase/create-rdx",
-  "version": "1.0.0-beta.9",
+  "version": "1.0.1",
   "description": "Create a new RDX documentation project.",
   "license": "MIT",
   "bin": {
@@ -13,7 +13,7 @@
     "README.md"
   ],
   "engines": {
-    "node": ">=20.9"
+    "node": "^22.18.0 || ^24.11.0"
   },
   "publishConfig": {
     "access": "public"

package/templates/default/README.md

@@ -2,16 +2,22 @@
 
 This documentation site was created with RDX.
 
-Requires Node.js 20.9 or newer. Use a currently supported Node.js LTS release.
+Requires Node.js 22.18+ (22.x) or 24.11+ (24.x). Use the latest patch of either line.
 
 ## Development
 
+Use the same package manager that installed the project:
+
 ```bash
 pnpm dev
+# npm alternative: npm run dev
+# Yarn alternative: yarn dev
 ```
 
 Edit files in `docs/` to create your documentation. RDX creates and maintains
 its internal runtime in `.rdx/`.
+If installation failed during creation, keep these files, fix the reported error
+and retry `pnpm install` (or `npm install` / `yarn install`) before starting.
 
 ## Optional versioning
 

package/templates/default/docs/examples/accordion.mdx

@@ -39,9 +39,9 @@ Keep the server running while editing your documentation.
 
     </AccordionContent>
   </AccordionItem>
-  <AccordionItem value="soon" disabled>
-    <AccordionTrigger>More examples (soon)</AccordionTrigger>
-    <AccordionContent>Not available yet.</AccordionContent>
+  <AccordionItem value="disabled" disabled>
+    <AccordionTrigger>Disabled example</AccordionTrigger>
+    <AccordionContent>This item demonstrates the disabled state.</AccordionContent>
   </AccordionItem>
 </Accordion>
 

package/templates/default/docs/examples/tabs.mdx

@@ -52,7 +52,7 @@ Each group works independently. Panels can contain normal Markdown and RDX compo
   <TabsList aria-label="Environment">
     <TabsTrigger value="development">Development</TabsTrigger>
     <TabsTrigger value="production">Production</TabsTrigger>
-    <TabsTrigger value="preview" disabled>Preview (soon)</TabsTrigger>
+    <TabsTrigger value="preview" disabled>Disabled example</TabsTrigger>
   </TabsList>
   <TabsContent value="development">
 

package/templates/default/package.json

@@ -9,8 +9,8 @@
     "start": "rdx start"
   },
   "dependencies": {
-    "@lexibase/rdx-ui": "1.0.0-beta.2",
-    "@lexibase/rdx-next": "1.0.0-beta.10",
+    "@lexibase/rdx-ui": "1.0.0",
+    "@lexibase/rdx-next": "1.0.1",
     "next": "^16.4.2",
     "react": "19.3.1",
     "react-dom": "19.3.1"
@@ -21,6 +21,6 @@
     "typescript": "6.0.3"
   },
   "engines": {
-    "node": ">=20.9"
+    "node": "^22.18.0 || ^24.11.0"
   }
 }

package/templates/default/rdx.config.ts

@@ -1,12 +1,33 @@
 import { defineConfig } from '@lexibase/rdx-next'
 
 export default defineConfig({
-  title: 'My documentation',
   description: 'Documentation built with RDX.',
+  // SEO and link previews. Paths starting with '/' refer to files in public/.
+  metadata: {
+    // The single site name: browser titles, social previews and default branding.
+    applicationName: 'My documentation',
+    // Set metadataBase to your public site URL to resolve relative share images.
+    // Optional examples below: uncomment only after adding the referenced files.
+    // icons: {
+    //   icon: [
+    //     { url: '/icon.svg', type: 'image/svg+xml' },
+    //     { url: '/icon.png', sizes: '96x96', type: 'image/png' },
+    //   ],
+    //   shortcut: '/favicon.ico',
+    // },
+    // icon: browser tab icons with optional sizes and MIME types.
+    // shortcut: traditional favicon link for browser compatibility.
+    // manifest: '/site.webmanifest',
+    // The web app manifest describes its name, icons, etc.; RDX does not create it.
+  },
+  // Floating heading navigation; shown only on pages with enough sections.
   TOC: false,
+  // Local documentation search in the navbar; no external search service needed.
   search: false,
+  // Optional navbar text does not change metadata.applicationName.
   navbar: {
-    title: '',
+    title: '', // Text beside the logo; empty or omitted shows only the logo.
+    // logo: Logo, // Import a React component that accepts className, not an image path.
     actions: {
       github: {
         visible: true,
@@ -15,6 +36,8 @@ export default defineConfig({
       showToggleMode: true,
     },
   },
+  // When disabled, '/' redirects to '/docs'.
+  // To use your own home.tsx, import its component and set homepage.component.
   homepage: {
     enabled: false,
   },