Installation

Quick Overview

Create Aether CMS projects with no build configuration and seamless update capabilities.

npx create-aether-cms my-cms-site
cd my-cms-site
npm start

Then open http://localhost:8080 to see your site.

When you're ready to deploy to production, create a static build with npm run build.

Creating a Project

Basic Installation

Option 1: Using npx (recommended)

npx create-aether-cms my-cms-site

Option 2: Using npm init

npm init aether-cms my-cms-site

Option 3: Using yarn create

yarn create aether-cms my-cms-site

Version-Specific Installation

# Install specific version
npx create-aether-cms my-blog --version v1.0.0

# Install specific git tag
npx create-aether-cms my-blog --tag stable

# Install specific commit
npx create-aether-cms my-blog --hash abc1234

# Show all available options
npx create-aether-cms --help

Available Version Options

Project Structure

This will create a directory called my-cms-site inside the current folder.
Inside that directory, it will generate the initial project structure and install the dependencies.

my-cms-site/
├── README.md
├── node_modules/
├── package.json
├── package-lock.json
├── .gitignore
├── .gitattributes          # ← NEW: Conflict-free updates
├── .env
├── index.js
├── core/
│   ├── admin/
│   ├── api/
│   ├── lib/
│   ├── routes/
│   └── utils/
├── assets/
│   ├── css/
│   └── js/                 # ← Includes: New update utilities
└── content/
    ├── data/
    │   └── settings.json   # ← Enhanced with update preferences
    ├── themes/
    └── uploads/

No configuration or complicated folder structures. Just the files you need to build your site.

What Happens During Installation

The installer automatically handles everything needed for a production-ready setup:

1. 🔄 Repository Cloning: Downloads the complete Aether CMS codebase
2. 🎯 Version Targeting: Switches to your specified version (if provided)
3. ⚙️ Git Configuration: Sets up update-friendly remotes and conflict resolution
4. 📦 Project Customization: Updates package.json with your project details
5. 🛠️ Update System: Creates helper scripts for seamless future updates
6. 📥 Dependencies: Installs all required npm packages
7. 🚀 Initialization: Creates your first commit and optional repository setup

Interactive Setup

During installation, you'll be prompted for optional configuration:

# Example installation flow
🌳 Creating Aether CMS project: my-blog
🎯 Target: version = v1.0.0
📥 Cloning Aether CMS repository...
🎯 Switching to version v1.0.0...
📦 Installing dependencies...
🔄 Configuring git for seamless updates...
✅ Configured upstream remote for updates

Connect to your own Git repository? (y/n): y
Repository URL: https://github.com/username/my-blog.git
✅ Added your repository as origin

Push now? (y/n): y
✅ Pushed to your repository

🎉 Success! Created my-blog with seamless update support

Enhanced Features

Projects created with the latest version include powerful capabilities out of the box:

🔄 Built-in Update System

# Check for updates
npm run check-updates

# Apply updates safely
npm run update-aether

📊 Installation Metadata

Your project tracks installation details for better update management:

{
  "aetherCMS": {
    "installedVersion": "v1.0.0",
    "installedAt": "2025-06-18T10:30:00.000Z",
    "installOptions": {
      "version": "v1.0.0",
      "tag": null,
      "hash": null
    }
  }
}

🛡️ Conflict-Free Updates

Automatic protection for your customization:

• ✅ Project name and version preserved
• ✅ Environment variables maintained
• ✅ Content and uploads protected
• ✅ Custom settings preserved

Requirements

• Node.js 18.x or later
• The latest version of npm installed
• Git (for version targeting and updates)
• macOS, Windows, and Linux are supported

Advantages Over Traditional Installation

Using create-aether-cms offers significant benefits over traditional npm packages:

1. 📁 Direct Code Access: All CMS code is in your project directory (not in node_modules)
2. 🎨 Complete Customization: Modify any file without ejecting or complex overrides
3. 🔄 Seamless Updates: Automated conflict-free updates preserve your customization
4. 🎯 Version Control: Install any specific version, tag, or commit
5. 🚀 Complete Application: Creates a fully functional project in one command
6. ⚡ Modern Architecture: ESM modules, clean structure, and best practices

Comparison with npm install

Next Steps

Once your project is created:

1. 🚀 Start developing: npm start launches your development server
2. 📝 Add content: Use the admin interface at /aether (admin/admin)
3. 🎨 Customize themes: Modify files in /content/themes/
4. 🔄 Stay updated: Use npm run check-updates regularly