Mapples CLI

A command-line interface for managing Mapples projects, enabling developers to initialize projects, synchronize pages from the API, and manage project configurations.

Installation

npm install -g @mapples/cli

Or using yarn:

yarn global add @mapples/cli

Usage

Initialize a Project

Initialize a new Mapples project with configuration:

mapples init

This command will:

• Prompt you for configuration values (sandbox URL, asset URL, API key, etc.)
• Create a .mapplesrc.json configuration file
• Update your .gitignore to exclude the configuration file

Manage Pages

Synchronize Pages from API

Fetch and create page components from the Mapples API:

mapples pages --sync

This command will:

• Fetch all pages from the configured API endpoint
• Generate React components using templates
• Create page directories with the following structure:

  mapples/pages/{PageName}/
  ├── {PageName}Mapplet.tsx
  ├── {PageName}.json
  ├── _meta_{PageName}.json
  ├── index.ts
  └── .donotedit

Show Pages Information

Display information about all pages in a formatted table:

mapples pages --info

This shows:

• Page names and UUIDs
• Creation and update timestamps
• Sync status (New, Synced, Update, Error)
• Color-coded status indicators

Configuration

The CLI uses a .mapplesrc.json file for configuration. Here are the available options:

{
  "sandboxUrl": "https://staging.mapples.org",
  "assetUrl": "https://staging.assets.mapples.org",
  "apiKey": "your-api-key-here",
  "useExpoRouter": false,
  "pagesDir": "pages",
  "styleDir": "style",
  "assetsDir": "assets",
  "sourceDir": "mapples"
}

Configuration Options

• sandboxUrl: The base URL for the Mapples API
• assetUrl: The base URL for Mapples assets
• apiKey: Your Mapples API key (required)
• useExpoRouter: Whether to use Expo Router for navigation
• pagesDir: Directory name for pages (default: "pages")
• styleDir: Directory name for styles (default: "style")
• assetsDir: Directory name for assets (default: "assets")
• sourceDir: Source directory name (default: "mapples")

Generated Files

When synchronizing pages, the CLI generates the following files for each page:

Component File ({PageName}Mapplet.tsx)

A React component that uses the @mapples/render package to render page content.

Data File ({PageName}.json)

Contains the page data fetched from the API.

Meta File (_meta_{PageName}.json)

Contains page metadata (excluding the data payload) for tracking updates.

Index File (index.ts)

Exports the page component for easy importing.

Protection File (.donotedit)

A marker file to prevent accidental editing of generated content.

Development

Prerequisites

• Node.js (v16 or higher)
• Yarn 4.10.2

Setup

1. Clone the repository:

git clone https://github.com/mapplesorg/cli.git
cd cli

2. Install dependencies:

yarn install

3. Build the project:

yarn build

Available Scripts

• yarn build - Build the project for development
• yarn build:prod - Build the project for production
• yarn dev - Build and watch for changes
• yarn clean - Remove the dist directory
• yarn format - Format code with Prettier
• yarn format:check - Check code formatting
• yarn lint - Run ESLint

Publishing

The package is automatically built for production before publishing:

yarn prepublishOnly

License

MIT

Author

Oleksandr Soloviov [email protected]

Repository

https://github.com/mapplesorg/cli