Create THLSPress App CLI

The create-thlspress-app is a command-line interface (CLI) tool designed to streamline the setup of a new THLSPress CMS project. It automates the process of creating a project directory, copying the base CMS template, configuring databases, installing optional modules, setting up an admin account, installing dependencies, and initializing a Git repository. This tool is particularly useful for developers starting a new THLSPress-based application, whether for local development, testing, or production deployment.

THLSPress CMS is a modern, monorepo-based content management system built with Next.js, Prisma, and TypeScript. The CLI ensures that your project is bootstrapped with best practices, including environment configuration, database schema synchronization, and static asset generation.

Prerequisites

Before using the CLI, ensure you have the following installed:

• Node.js: Version 18 or higher (LTS recommended).
• Package Manager: npm, Yarn, or pnpm (the CLI auto-detects and uses your default).
• Docker (optional): Required if you want to automatically spin up a local PostgreSQL or MySQL database for development.
• Git (optional): For repository initialization.
• Prisma CLI: Installed globally via npm install -g prisma or handled via npx in the project.

The CLI is part of the THLSPress monorepo and can be built and run from the source. If you're using the published package, install it via your package manager (e.g., pnpm add -g create-thlspress-app).

Installation

Global Installation (Recommended)

Install the CLI globally from npm for easy access:

npm install -g create-thlspress-app

Then run it directly:

create-thlspress-app [project-name]

This method uses the published package and doesn't require cloning the repository.

From Source (For Development or Contribution)

If you want to use or contribute to the source code:

1. Clone the THLSPress monorepo:

   git clone https://github.com/TheLoloS/thlspress-cms.git
   cd thlspress-cms

2. Install dependencies:

   pnpm install

3. Build the CLI package:

   pnpm build --filter create-thlspress-app

4. Run the CLI using npx (from the monorepo root):

   npx create-thlspress-app [project-name]

Usage

The CLI is invoked via the command line with an optional project name argument and various flags for customization.

Basic Command

npx create-thlspress-app my-project

This will:

• Prompt for project details if not provided.
• Copy the base CMS template.
• Guide through database setup.
• Install dependencies and configure the project.

Full Command with Options

npx create-thlspress-app my-project --db-provider postgresql --db-url "postgresql://user:pass@localhost:5432/db" --admin-email admin@example.com --admin-name admin --admin-password securepass --skip-install --no-git -y

Command-Line Options

• Interactive Mode: Without --yes, the CLI will prompt for missing options like project name, database provider, admin details, and module selection.
• Non-Interactive Mode: Use --yes for CI/CD or scripted setups, providing all options via flags.

Exit Codes

• 0: Success.
• 1: General error (e.g., invalid input, failed copy, or installation issues).

Step-by-Step Process

When you run the CLI, it performs the following steps automatically:

1. Project Directory Creation:

   • Creates a new directory for the project (e.g., my-project).
   • Validates that the directory is empty or doesn't exist.

2. Template Copying:

   • Copies the base CMS template from the monorepo's cms/ folder.
   • Excludes build artifacts like node_modules, .next, and prisma/migrations.
   • Configures thlspress.json with a unique project ID and version from package.json.

3. Database Configuration:

   • Prompts for or uses the specified database provider.
   • For SQLite: Sets a local file-based URL (file:./dev.db).
   • For PostgreSQL/MySQL:
     • Checks for Docker availability.
     • If Docker is present and opted-in, starts a temporary container with a random database name and exposes it on the default port (5432 for PG, 3306 for MySQL).
     • Falls back to manual URL input if Docker is unavailable or declined.
   • Copies the appropriate Prisma schema (schema.prisma, schema.postgresql, or schema.sqlite) to prisma/schema.prisma.

4. Module Selection:

   • Prompts for optional modules (e.g., "Reservation" for booking systems).
   • Installs selected modules using the internal addModule function from thlspress-cli.

5. Admin Account Creation (Optional):

   • If database is configured, prompts to create an admin user.
   • Validates email format.
   • Stores credentials for use in seeding.

6. Dependency Installation:

   • Detects your package manager (pnpm > yarn > npm).
   • Runs pnpm install (or equivalent) unless --skip-install is used.

7. Database Setup and Seeding:

   • Sets DATABASE_URL environment variable.
   • Runs npx prisma db push --skip-generate to sync the schema.
   • If admin details provided, runs npx tsx scripts/init-db.ts to create the admin user and a welcome page.

8. Environment File Generation:

   • Creates .env with:
     • NextAuth URL and secret.
     • Encryption key.
     • Database URL (or placeholder).

9. Git Initialization (Optional):

   • Runs git init, adds a basic .gitignore, stages files, and commits an initial snapshot unless --no-git is used.

10. Static Asset Generation:

    • Runs pnpm run generate:static-classes and pnpm run regenerate:all to build CSS and other static files.

Output and Next Steps

Upon completion, the CLI displays:

• Success message.
• Admin credentials (if created).
• Instructions:
  • cd my-project
  • Set DATABASE_URL if not configured.
  • Run pnpm run dev to start the development server.
  • Note: Run npx prisma generate if new modules add database models.

Example output snippet:

🎉 Congratulations! Your THLSPress project is ready!

Next steps:
   1. cd my-project
   2. Run the development server: pnpm run dev

Examples

Quick Local Setup with SQLite

npx create-thlspress-app quick-app --db-provider sqlite -y

• Uses defaults, SQLite for easy local dev, skips prompts.

Docker-Based PostgreSQL Setup

npx create-thlspress-app prod-app --db-provider postgresql -y

• Auto-starts a Docker PostgreSQL container if Docker is available.

Custom Database with Admin

npx create-thlspress-app custom-app --db-url "mysql://root:pass@localhost:3306/my_db" --admin-email "user@domain.com" --admin-name "customadmin" --admin-password "strongpass"

• Connects to an existing MySQL database and creates a custom admin.

Skip Install and Git

npx create-thlspress-app no-install-app --skip-install --no-git

• Useful for manual control over dependencies and version control.

Customization

• Modules: Extend the CLI by adding more choices in the prompts.multiselect for modules. Currently supports "Reservation".
• Templates: The base template is sourced from cms/ in the monorepo. Customize it there for project-wide changes.
• Database Schemas: Provider-specific schemas are in cms/prisma/schema.<provider>. Edit these for custom models.
• Seeding Script: The scripts/init-db.ts handles admin creation and welcome content. Modify for additional seeding logic.

Troubleshooting

Common Issues

1. "Directory already exists and is not empty":

   • Choose a different project name or clear the directory.

2. Docker Not Starting:

   • Ensure Docker is running and you have permissions.
   • Check logs: docker logs <container-name>.
   • Fallback: Provide a manual --db-url.

3. Prisma Errors During db push:

   • Verify DATABASE_URL in .env.
   • Run npx prisma validate to check schema.
   • For migrations: Use npx prisma migrate dev instead of db push in production.

4. Dependency Installation Fails:

   • Run manually: cd my-project && pnpm install.
   • Clear cache: pnpm store prune.

5. Git Init Fails:

   • Ensure Git is installed and in PATH.
   • Use --no-git and initialize manually.

6. Module Installation Issues:

   • Ensure thlspress-cli is built in the monorepo.
   • Check addModule logs for errors.

Logs and Debugging

• The CLI uses ora spinners for progress and chalk for colored output.
• Errors are logged to stderr with details (e.g., execSync output).
• For verbose mode, wrap calls with { stdio: 'inherit' } in custom forks.

Environment Variables

The CLI respects npm_config_user_agent for package manager detection. Set it manually if needed (e.g., npm_config_user_agent=pnpm).

Advanced Topics

Integrating with CI/CD

Use --yes with all options for automated setups:

npx create-thlspress-app ci-app --db-provider sqlite --admin-email ci@fake.com -y

Extending the CLI

The source is in packages/create-thlspress-app/src/index.ts. Key sections:

• Prompts: Uses prompts library for user input.
• ExecSync: For shell commands (e.g., Docker, Prisma).
• File Operations: fs-extra for copying and JSON handling.

To add features:

• New prompts for custom configs.
• Additional execSync steps for tools like ESLint setup.

Security Notes

• Generated secrets (NextAuth, encryption) are random and base64-encoded.
• Admin passwords are prompted securely (no echo).
• Docker containers use --rm for auto-cleanup.
• Always use strong passwords and secure your .env file (gitignored by default).

Contributing

If you're contributing to the THLSPress monorepo:

1. Build the package: pnpm build --filter create-thlspress-app.
2. Test locally: Run the CLI from the root.
3. Add tests in packages/create-thlspress-app/tests/.

For issues or features, open a GitHub issue in the THLSPress CMS repository.

Last Updated: September 21, 2025
Version: Matches THLSPress CMS v[package.json version]