npm package: @robarkesteijn/nexus
Description: A Nuxt layer providing a CMS system with page management, templates, media handling, and authentication
Latest version: 0.1.0

# CMS Layer for Nuxt

A **Nuxt layer** providing a complete, self-hosted CMS system with authentication, user management, and content editing features. Designed to be extended by other Nuxt applications through the Nuxt **layers system**.

[![npm version](https://img.shields.io/npm/v/@robarkesteijn/nexus)](https://www.npmjs.com/package/@robarkesteijn/nexus)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Installation

```bash
npm install @robarkesteijn/nexus
# or
pnpm add @robarkesteijn/nexus
# or
yarn add @robarkesteijn/nexus
```

## Quick Start

In your Nuxt project's `nuxt.config.ts`:

```typescript
export default defineNuxtConfig({
  extends: ['@robarkesteijn/nexus'],
})
```

That's it! The CMS layer will automatically provide:
- Admin dashboard at `/admin`
- Authentication system
- User management
- Content management (pages, templates)
- Media management
- All necessary API routes and components

## Core Features

- **Authentication & Sessions**
  - Login/logout system with secure password hashing (`bcryptjs`)
  - Session management via cookies
  - Middleware to protect `/admin` routes

- **User Management**
  - Admin dashboard for managing users
  - Add, edit, and delete users through a UI
  - Role-based permissions (`admin`, `editor`, `viewer`)
  - Passwords are always stored securely and never exposed

- **Content Management**
  - ✅ Full CRUD for posts/pages stored in SQLite
  - Post status management (draft, published, archived)
  - Slug-based URLs and SEO-friendly structure
  - Extensible design for handling additional content types

- **Media Management**
  - 🔶 Basic upload infrastructure in place
  - Local file storage in Docker volume
  - Designed to work without third-party storage providers

- **Persistence**
  - Uses **SQLite (`better-sqlite3`)** for simplicity and portability
  - Database and uploaded files stored in a mounted `.data` volume (survives redeploys)
  - Optionally containerized with **Docker** for both development and production

- **UI**
  - Built with **Nuxt UI 4.x** for modern, accessible components
  - Custom theme with spring-green primary colors
  - Uses modals, forms, data tables, and toasts for a clean admin interface

## Philosophy

- Keep it **lightweight** and **self-contained**
- Minimize reliance on external SaaS (can be hosted anywhere)
- Easy to extend via Nuxt **layers** so each new site reuses the CMS core

---

## Requirements

- **Node.js**: >=24.0.0 <25.0.0
- **pnpm**: >=10.0.0 <11.0.0 (or npm/yarn)
- **Nuxt**: ^4.0.0

## Links

- 📦 [npm package](https://www.npmjs.com/package/@robarkesteijn/nexus)
- 🐙 [GitHub repository](https://github.com/RobArkesteijn/nuxt-cms-layer)
- 📚 [Nuxt Layers Documentation](https://nuxt.com/docs/getting-started/layers)

---

# 🛠️ Development

This section is for **developing the layer itself**. If you just want to use the layer, see [Installation](#installation) above.

The project includes a `.playground` directory for testing the layer during development.

## Local Development (without Docker)

```bash
# Install dependencies
pnpm install

# Run development server
pnpm dev

# Build for production
pnpm build

# Preview production build
pnpm preview
```

## Docker Development

This project uses **Docker** with separate configs for **production** and **development**.  

## 📦 Requirements
- [Docker](https://docs.docker.com/get-docker/) installed
- [Docker Compose](https://docs.docker.com/compose/) v2+
- `make` (for convenience commands)

## 🔹 Running in Development (Hot Reload)

Run the Nuxt dev server inside Docker:

```sh
make dev
```

Stop with:
```sh
make down
```

## 🔹 Running in Production Mode

Builds and serves the optimized Nuxt app:

```sh
make prod
```

Stop with:
```sh
make down
```

## 🔹 Rebuilding Containers

Rebuild production:

```sh
make rebuild
```

Rebuild development:
```sh
make rebuild-dev
```

## 🔹 Volumes

cms-data → persisted at /srv/cms-data inside the container

To remove everything (including volumes):

```sh
make clean
```

## 🔹 First Time Setup

When starting the application for the first time (or after removing volumes), a default admin user will be automatically created:

- **Email**: `admin@example.com` (or set `DEFAULT_ADMIN_EMAIL` environment variable)
- **Password**: `admin123` (or set `DEFAULT_ADMIN_PASSWORD` environment variable)
- **Role**: Admin

**⚠️ Important**: Change the default password after first login for security!

### Environment Variables

You can customize the default admin user by setting these environment variables:

```bash
DEFAULT_ADMIN_EMAIL=your-email@example.com
DEFAULT_ADMIN_PASSWORD=your-secure-password
```

## 🔹 Enter Dev Container Shell
```sh
make shell
```

Opens an interactive shell inside the running dev container.
Useful for running commands like:

```sh
pnpm add <package>       # Install new dependencies
pnpm update              # Update packages
ls node_modules          # Inspect installed dependencies
```

## Publishing

This package is automatically published to npm when a GitHub release is created. See the [GitHub Actions workflow](.github/workflows/publish.yml) for details.

To publish manually:
```bash
npm publish --access public
```

## License

MIT