Installation

This document provides detailed installation instructions for ReX in various environments and configurations.

Prerequisites

Before installing ReX, ensure your environment meets these requirements:

• Node.js: Version 16.x or higher
• npm or pnpm: For package management
• TypeScript: Version 4.7 or higher (for TypeScript projects)

Core Installation

Install the core package, which provides the foundation for all ReX functionality:

# Using npm
npm install @ReX/core

# Using pnpm
pnpm add @ReX/core

# Using yarn
yarn add @ReX/core

Environment-Specific Packages

Install additional packages based on your target environment:

Node.js Environment

For server-side applications:

# Using npm
npm install @ReX/node

# Using pnpm
pnpm add @ReX/node

# Using yarn
yarn add @ReX/node

This package provides:

• FileSystemAdapter for filesystem storage
• FileSystemWatcher for real-time file change detection
• Node.js-specific utilities and helpers

Browser Environment

For client-side applications:

# Using npm
npm install @ReX/browser

# Using pnpm
pnpm add @ReX/browser

# Using yarn
yarn add @ReX/browser

This package provides:

• IndexedDBAdapter for persistent browser storage
• LocalStorageAdapter for simple key-value storage
• ServiceWorkerAdapter for offline capabilities
• Browser-specific utilities and helpers

React Integration

For React applications:

# Using npm
npm install @ReX/react

# Using pnpm
pnpm add @ReX/react

# Using yarn
yarn add @ReX/react

This package provides:

• ContentProvider for React context integration
• useContent hook for reading content with automatic updates
• useContentWrite hook for writing content
• Additional React-specific components and utilities

Optional Extensions

MDX Processing

For working with MDX content:

# Using npm
npm install @ReX/mdx

# Using pnpm
pnpm add @ReX/mdx

# Using yarn
yarn add @ReX/mdx

Schema Validation

For content validation with JSON Schema:

# Using npm
npm install @ReX/validation

# Using pnpm
pnpm add @ReX/validation

# Using yarn
yarn add @ReX/validation

Environment Configuration

TypeScript Configuration

If using TypeScript, ensure your tsconfig.json includes these settings:

{
  "compilerOptions": {
    "target": "ES2020",
    "lib": ["DOM", "DOM.Iterable", "ESNext"],
    "module": "ESNext",
    "moduleResolution": "node",
    "esModuleInterop": true,
    "strict": true,
    "paths": {
      "@lib/*": ["./src/lib/*"],
      "@components/*": ["./src/components/*"]
    }
  }
}

Path Aliases

If using path aliases, configure them in your build system:

Vite

For Vite projects, configure vite.config.ts:

import { defineConfig } from 'vite'
import path from 'path'

export default defineConfig({
  resolve: {
    alias: {
      '@lib': path.resolve(__dirname, './src/lib'),
      '@components': path.resolve(__dirname, './src/components'),
    },
  },
})

Next.js

For Next.js projects, use the next.config.js file:

const nextConfig = {
  webpack(config) {
    config.resolve.alias = {
      ...config.resolve.alias,
      '@lib': path.resolve(__dirname, './src/lib'),
      '@components': path.resolve(__dirname, './src/components'),
    }
    return config
  },
}

module.exports = nextConfig

Installation Verification

Verify your installation by creating a simple test file:

import { createContentStore } from '@ReX/core'
import { createMemoryAdapter } from '@ReX/core/adapters/common/memory'

async function testInstallation() {
  // Create a memory-based content store
  const store = createContentStore({
    adapter: createMemoryAdapter(),
  })

  // Write test content
  await store.write('test.md', {
    data: '# Test Content',
    contentType: 'text/markdown',
    metadata: {
      title: 'Test Content',
      createdAt: new Date(),
    },
  })

  // Read content back
  const content = await store.read('test.md')
  console.log('Successfully read content:', content)

  // Dispose of resources
  await store.dispose()
}

testInstallation().catch(console.error)

Environment-Specific Setup

Node.js Setup

For a Node.js application:

import { createContentStore } from '@ReX/core'
import { createFileSystemAdapter } from '@ReX/node'
import path from 'path'

// Create content store with filesystem adapter
const store = createContentStore({
  adapter: createFileSystemAdapter({
    baseDir: path.resolve(__dirname, 'content'),
    watch: true, // Enable file watching
    encoding: 'utf-8', // Default text encoding
    createDir: true, // Create content directory if it doesn't exist
  }),
})

export default store

Browser Setup

For a browser application:

import { createContentStore } from '@ReX/core'
import { createIndexedDBAdapter } from '@ReX/browser'

// Create content store with IndexedDB adapter
const store = createContentStore({
  adapter: createIndexedDBAdapter({
    dbName: 'content-store', // IndexedDB database name
    storeName: 'content', // Object store name
    version: 1, // Database version
  }),
})

export default store

React Application Setup

For a React application:

import React from 'react'
import { createContentStore } from '@ReX/core'
import { ContentProvider } from '@ReX/react'
import { createMemoryAdapter } from '@ReX/core/adapters/common/memory'

// Configure content store
const configureStore = () => {
  return createContentStore({
    adapter: createMemoryAdapter({
      initialContent: {
        'welcome.md': {
          data: '# Welcome\n\nThis is a sample content.',
          contentType: 'text/markdown',
          metadata: {
            title: 'Welcome',
            createdAt: new Date(),
          },
        },
      },
    }),
  })
}

// Root application component
function App() {
  const store = React.useMemo(() => configureStore(), [])

  return (
    <ContentProvider store={store}>
      <YourApplication />
    </ContentProvider>
  )
}

export default App

Troubleshooting

Common Installation Issues

Module Resolution Errors

If you encounter module resolution errors:

Error: Cannot find module '@ReX/core' or its corresponding type declarations.

Solutions:

1. Verify package installation: npm list @ReX/core
2. Check for typos in import statements
3. Ensure your build system is configured correctly
4. Try clearing cache: npm cache clean --force

Peer Dependency Warnings

If you see peer dependency warnings:

warning " > @ReX/[email protected]" has unmet peer dependency "@ReX/core@^1.0.0"

Solution: Install the required peer dependency with a compatible version:

npm install @ReX/core@^1.0.0

TypeScript Path Alias Issues

If TypeScript cannot resolve path aliases:

1. Ensure your tsconfig.json has correct paths configuration
2. Make sure your build system (Webpack, Vite, etc.) has matching alias configuration
3. Restart your development server and TypeScript server

Next Steps

After installation:

1. Follow the Getting Started guide
2. Explore Key Concepts to understand the system
3. Check the Reference Documentation for detailed API information