@lexibase/create-rdx 1.0.0-beta.8 → 1.0.0

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.8",
+  "version": "1.0.0",
   "description": "Create a new RDX documentation project.",
   "license": "MIT",
   "bin": {
@@ -13,7 +13,7 @@
     "README.md"
   ],
   "engines": {
-    "node": ">=18.18"
+    "node": "^22.18.0 || ^24.11.0"
   },
   "publishConfig": {
     "access": "public"

package/templates/default/README.md

@@ -2,14 +2,22 @@
 
 This documentation site was created with RDX.
 
+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
 
@@ -19,8 +27,8 @@ pnpm rdx version 1.0.0
 ```
 
 The first command installs the official plugin, activates it in `rdx.config.ts`
-and prepares the runtime. It preserves existing options and saves a backup
-before changing the configuration. Restart `pnpm dev` afterward. Repeated
+and prepares the runtime. It preserves existing options and validates the
+configuration before saving it, without creating backup files. Restart `pnpm dev` afterward. Repeated
 activation does not duplicate the plugin or upgrade its installed version.
 If the configuration is too dynamic to edit safely, follow the manual
 instructions printed by the CLI. Installing a package alone does not activate it.

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

@@ -0,0 +1,69 @@
+---
+title: Accordion
+description: Keep optional explanations close without crowding the page.
+link_position: 6
+---
+
+## Frequently asked questions
+
+Use Enter or Space to expand an item. Tab moves between questions and links.
+One item opens at a time; selecting it again closes it.
+
+<Accordion>
+  <AccordionItem value="content">
+    <AccordionTrigger>Where do I write my documentation?</AccordionTrigger>
+    <AccordionContent>
+
+Create folders and `.mdx` files inside **docs/**. Each folder becomes a category
+and each file becomes a page.
+
+Read the [introduction](/docs/init/intro) to get started.
+
+    </AccordionContent>
+  </AccordionItem>
+  <AccordionItem value="preview">
+    <AccordionTrigger>How do I preview my changes?</AccordionTrigger>
+    <AccordionContent>
+
+Run the development server:
+
+```bash
+pnpm dev
+```
+
+<Callout variant="tip" title="Live updates">
+
+Keep the server running while editing your documentation.
+
+</Callout>
+
+    </AccordionContent>
+  </AccordionItem>
+  <AccordionItem value="disabled" disabled>
+    <AccordionTrigger>Disabled example</AccordionTrigger>
+    <AccordionContent>This item demonstrates the disabled state.</AccordionContent>
+  </AccordionItem>
+</Accordion>
+
+## Production checklist
+
+Opening an answer closes the previous one in the same group.
+
+<Accordion>
+  <AccordionItem value="build">
+    <AccordionTrigger>Build for production</AccordionTrigger>
+    <AccordionContent>
+
+Run `pnpm build` to generate the production site.
+
+    </AccordionContent>
+  </AccordionItem>
+  <AccordionItem value="start">
+    <AccordionTrigger>Check the production site</AccordionTrigger>
+    <AccordionContent>
+
+Run `pnpm start` after a successful build.
+
+    </AccordionContent>
+  </AccordionItem>
+</Accordion>

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

@@ -0,0 +1,56 @@
+---
+title: Callouts
+description: Highlight notes, tips and important information.
+link_position: 4
+---
+
+## Highlight important information
+
+Callouts are included in RDX. No import or plugin is required.
+
+<Callout title="A useful note">
+
+Keep supporting information close to the documentation it explains.
+
+</Callout>
+
+<Callout variant="tip" title="A helpful tip">
+
+You can use **Markdown**, [documentation links](/docs/init/intro), and `inline code` inside a callout.
+
+</Callout>
+
+<Callout variant="success" title="Ready to go">
+
+Your documentation is ready to share.
+
+</Callout>
+
+<Callout variant="warning" title="Before updating">
+
+- Read the release notes.
+- Test your changes before deploying.
+
+</Callout>
+
+<Callout variant="danger" title="Irreversible action">
+
+Deleting the source files permanently removes their content.
+
+</Callout>
+
+<Callout>
+
+A title is optional. The default variant is `note`.
+
+</Callout>
+
+## Syntax
+
+```mdx
+<Callout variant="warning" title="Before updating">
+
+Test your changes before deploying.
+
+</Callout>
+```

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

@@ -0,0 +1,38 @@
+---
+title: Document links
+description: Link to documentation files using their relative paths.
+link_position: 7
+---
+
+## Link to a page
+
+Read the [introduction](../init/intro.mdx) or learn how to
+[create a page](../init/getting-started.mdx#create-a-page).
+
+```md
+[Introduction](../init/intro.mdx)
+[Create a page](../init/getting-started.mdx#create-a-page)
+```
+
+RDX resolves these paths relative to this file. When viewing a snapshot,
+links stay inside that snapshot instead of switching to Current.
+
+## Link to a section
+
+Jump to the [tables example](./markdown.mdx#tables), or return to
+[the first section](#link-to-a-page) of this page.
+
+Markdown headings receive automatic IDs. Repeated headings get suffixes such as
+`tables-1`. Relative document links must include the `.mdx` extension.
+
+<Callout title="Keep links portable">
+
+Use forward slashes and match the file's name and capitalization. If a destination
+does not exist in the current version, RDX reports the source file and link to fix.
+
+</Callout>
+
+## Assets and external links
+
+[External links](https://example.com/), `/images/logo.svg` and paths to downloads
+are not rewritten. Put public assets in `public/` and reference them from `/`.

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

@@ -13,3 +13,50 @@ link_position: 1
 ```ts
 const framework = 'RDX'
 ```
+
+## Tables
+
+| Feature | Available |
+| :------ | --------: |
+| Markdown tables | Yes |
+| Callouts | Yes |
+| Code blocks | Yes |
+| Blockquotes | Yes |
+
+### Five-column comparison
+
+Wider tables scroll horizontally on small screens without widening the page.
+
+| Feature | Description | Status | Plugin | Example |
+| :------ | :---------- | :----: | :----: | :------ |
+| Markdown | Write headings, lists, and paragraphs | Included | Not required | `## Heading` |
+| Callout | Highlight contextual information | Included | Not required | `<Callout>` |
+| Code block | Display source code with a copy button | Included | Not required | `pnpm dev` |
+| Blockquote | Quote a passage or explanation | Included | Not required | `> A quotation` |
+
+## Task lists
+
+- [x] Create a documentation project
+- [ ] Add your own pages
+
+> Keep explanations close to the content they describe.
+>
+> A quotation can contain **formatted text**, [links](/docs/init/intro), and `inline code`.
+
+You can also use ~~strikethrough~~ text.
+
+## Syntax highlighting
+
+Put the language after the opening fence, such as `tsx`, `json`, `bash`, `py`
+or `css`. Colors follow your site's light/dark theme automatically. Unlabelled
+or unknown languages remain readable as plain text.
+
+```tsx
+export function Welcome() {
+  return <h1>Welcome to RDX</h1>
+}
+```
+
+```json
+{ "framework": "RDX", "minimal": true }
+```

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

@@ -0,0 +1,72 @@
+---
+title: Tabs
+description: Group related examples without leaving the page.
+link_position: 5
+---
+
+## Choose your package manager
+
+Tabs are included in RDX. No import or plugin is required.
+Use the arrow keys to move between tabs and Enter or Space to select one.
+
+<Tabs defaultValue="pnpm">
+  <TabsList aria-label="Package manager">
+    <TabsTrigger value="npm">npm</TabsTrigger>
+    <TabsTrigger value="pnpm">pnpm</TabsTrigger>
+    <TabsTrigger value="yarn">yarn</TabsTrigger>
+  </TabsList>
+  <TabsContent value="npm">
+
+Install dependencies with **npm**:
+
+```bash
+npm install
+```
+
+  </TabsContent>
+  <TabsContent value="pnpm">
+
+Install dependencies with **pnpm**:
+
+```bash
+pnpm install
+```
+
+  </TabsContent>
+  <TabsContent value="yarn">
+
+Install dependencies with **yarn**:
+
+```bash
+yarn install
+```
+
+  </TabsContent>
+</Tabs>
+
+## Keep related information together
+
+Each group works independently. Panels can contain normal Markdown and RDX components.
+
+<Tabs defaultValue="development">
+  <TabsList aria-label="Environment">
+    <TabsTrigger value="development">Development</TabsTrigger>
+    <TabsTrigger value="production">Production</TabsTrigger>
+    <TabsTrigger value="preview" disabled>Disabled example</TabsTrigger>
+  </TabsList>
+  <TabsContent value="development">
+
+<Callout variant="tip" title="Live updates">
+
+Run `pnpm dev` and edit your documentation to see changes locally.
+
+</Callout>
+
+  </TabsContent>
+  <TabsContent value="production">
+
+1. Run `pnpm build`.
+2. Run `pnpm start` to check the production site.
+
+  </TabsContent>
+</Tabs>

package/templates/default/package.json

@@ -9,18 +9,18 @@
     "start": "rdx start"
   },
   "dependencies": {
-    "@lexibase/rdx-ui": "^1.0.0-beta.1",
-    "@lexibase/rdx-next": "^1.0.0-beta.9",
-    "next": "^15.5.0",
-    "react": "19.1.0",
-    "react-dom": "19.1.0"
+    "@lexibase/rdx-ui": "1.0.0",
+    "@lexibase/rdx-next": "1.0.0",
+    "next": "^16.4.2",
+    "react": "19.3.1",
+    "react-dom": "19.3.1"
   },
   "devDependencies": {
     "@types/node": "^22.15.3",
-    "@types/react": "19.1.0",
-    "typescript": "5.9.2"
+    "@types/react": "19.3.0",
+    "typescript": "6.0.3"
   },
   "engines": {
-    "node": ">=18.18"
+    "node": "^22.18.0 || ^24.11.0"
   }
 }

package/templates/default/rdx.config.ts

@@ -1,10 +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,
@@ -13,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,
   },