Using the THLSPress CLI

The thlspress-cli is a powerful command-line tool that serves as the primary interface for managing modules within a THLSPress project. It is designed to be run via npx in an end-user's project, ensuring they always use the latest version without needing a global installation.

Main Command: add

The core functionality of the CLI is to add new modules to an existing THLSPress installation.

Synopsis

npx thlspress-cli@latest add <module-name...>

• <module-name...>: A space-separated list of one or more official module names to install (e.g., reservation, store).

The Installation Process Explained

When you run npx thlspress-cli add reservation, the CLI performs a sophisticated, multi-step process to safely and correctly integrate the module:

1. Configuration Check:

   • The CLI first looks for a thlspress.json file in the current directory to identify an existing THLSPress project.
   • It checks if the requested module is already installed and compares versions. If a newer version is available, it will prompt the user to update.

2. Template Fetching:

   • The CLI fetches the specified module template from the official THLSPress templates repository on GitHub.

3. File Scaffolding:

   • It copies the entire contents of the template's /app directory into the user's project's /app directory, preserving the folder structure. This adds all the necessary pages, components, and API routes.

4. Dependency Management:

   • It reads the dependencies and devDependencies from the module's module.json manifest.
   • It intelligently adds these dependencies to the user's package.json, ensuring specific, tested versions are used.
   • Finally, it runs the project's package manager (npm install, pnpm install, etc.) to download and install the new dependencies.

5. Database Schema Modification (prisma.schema):

   • The CLI processes the append.prisma.snippet file from the module, appending new models and enums to the user's schema.prisma at the // THLSPRESS:MODELS:APPEND marker.
   • It then processes inject.prisma.snippet, injecting new fields and relations into existing core models at their respective // THLSPRESS:INJECT:<MODEL_NAME> markers.

6. Code Modifications (Codemods):

   • The CLI scans the template's /codemods directory for snippet files.
   • For each snippet (e.g., sidebar.snippet.ts), it parses the // @@IMPORTS section to add required imports and the // @@TARGET section to inject code blocks into predefined markers in the target files.

7. Configuration Update:

   • Upon successful installation, the CLI updates the thlspress.json file, recording the newly installed module and its version.

8. Final Instructions:

   • The CLI outputs a success message and reminds the user to run npx prisma generate and npx prisma db push to finalize the database changes.

This automated process ensures that modules are installed consistently and correctly, minimizing the potential for manual error.