Welcome to the Homelab-Alpha npm Workspaces Template repository!

This project is a boilerplate for Node.js projects using npm workspaces. It provides a structured setup with client and server workspaces for modular full-stack development.

• Create a final pre-release checklist.

• Pending tasks (to be defined).

• Pending tasks (to be defined).

• Pending tasks (to be defined).

• Remove the Caution notice once the project reaches a stable phase.
• Create an ROADMAP.md
• Update the CHANGELOG.md

This template offers the following key features:

• npm Workspaces: Efficiently manages multi-package repositories.
• Automated Project Setup: Includes an initialization script to automate the initial configuration and setup process.
• Modular Workspaces:
  • Frontend (Client): Built with Vue.js 3, Vite, and TypeScript. Includes Pinia for state management and Vue Router for routing.
  • Backend (Server): A lightweight Express.js server.
• Tooling: Comes with ESLint and Prettier for code consistency, and Vitest and Playwright for comprehensive testing.
• Docker Integration: Containerized development and deployment with Docker and Docker Compose.
• Multi-Stage Dockerfile: Optimized Dockerfile for efficient builds and smaller images.
• Environment-Specific Docker Compose: Separate configurations for build, test, and production environments.
• Easy Setup: Quickly get started with full-stack JavaScript development.
• Minimal Config: Designed for fast, straightforward project initialization.

Ensure you have the following installed:

• Git (version: 2.50.0 or higher recommended)
• Node.js (version: 22.17.0 or higher recommended)
• npm (version: 10.9.0 or higher recommended)
• Docker Desktop (includes Docker Engine and Docker Compose)

To initialize a new project based on this template, follow these steps.

Open your terminal and run the following command:

git clone https://github.com/homelab-alpha/npm-workspaces-template.git

Change into the newly cloned project directory:

cd npm-workspaces-template

Run the init.sh script to prepare the npm workspaces for your new project. This script handles the initial setup, including cleaning up template-specific files and configuring the project for use.

./scripts/init.sh

This script will guide you through the following:

• Removing existing Git history: The .git directory will be removed to dissociate the new project from the template's Git history.
• Setting up a new Git repository (Optional): You will be prompted to initialize a new Git repository for your project.
• Updating project details: The script will assist you in updating relevant project details in the root, client and server package.json and Docker Compose files.

From the root directory of your project, install all required dependencies:

npm install

Once the project is set up, you can use the following commands for development, testing, and deployment.

To run the project directly on your machine:

This command will start both the client (Vite) and server (Express.js) in development mode.

npm run dev

The application should be accessible in your web browser at http://localhost:5173.

To get the project running locally using Docker and Docker Compose, follow these steps:

Follow the steps below to build Docker images and run the application in a local production-like environment.

Use the build configuration file to create the necessary images:

docker compose --file docker/compose.build.yml build

Start the production containers using:

docker compose --file docker/compose.prod.yml up

To run the containers in the background (detached mode), use:

docker compose --file docker/compose.prod.yml up --detach

Once the containers are running, access the app at:

http://localhost:5173

To stop containers running in the foreground, press CTRL+C, then run:

docker compose --file docker/compose.prod.yml down

For containers running in detached mode, just run:

docker compose --file docker/compose.prod.yml down

This command stops and removes the container and network, ensuring a clean state after use.

To execute the test suite inside a Docker container:

docker compose --file docker/compose.test.yml up --build --abort-on-container-exit

This command will build the test image, run the test command (e.g., npm run test --workspace=server), and exit once the tests are complete.

After the tests are completed, run the following command to remove the container service (npm-workspaces-template-test) and its network.

docker compose --file docker/compose.test.yml down

This command stops and removes the container and network that were created by the up command, ensuring a clean state.

This project uses ESLint for code linting, Prettier for code and Markdown file linting.

To check for any linting or formatting issues across all workspaces and Markdown files:

npm run format:check

This command will run format:check for both the client and server workspaces, and then markdown:format:check for all Markdown files.

To automatically fix any linting and formatting issues across all workspaces and Markdown files:

npm run format

This command will run format for the client and server workspaces, and markdown:format for all Markdown files.

To automatically fix most linting and formatting issues:

npm run lint

This command will run lint for both the client and server workspaces, and then markdown:lint for all Markdown files.

This repository serves as a template. If you want to contribute to the template's development, please follow these steps:

1. Fork the repository
2. Clone your forked repository: git clone https://github.com/your-username/npm-workspaces-template.git
3. Install the dependencies npm ci
4. Create a new branch for your feature or bug fix
5. Submit a pull request from your branch to our main branch

For more detailed guidelines, please refer to the CODE OF CONDUCT, CONTRIBUTING, and Code Style and Standards Guide files.

The Homelab-Alpha team strives to provide a seamless experience. Below, we document any known bugs, limitations, or issues you might encounter while using this template. This section will be regularly updated to reflect the latest information.

No known issues at this time.

If you discover a bug or experience an issue not listed here, please help us improve by opening an issue on GitHub.

Get started in seconds by running the command below in your terminal. This single command streamlines the setup process for you.

This will:

• Clone the npm Workspaces Template repository.
• Run the included init.sh initialization script.
• Re-evaluate the shell's current directory to reflect any changes made by the initialization script.
• Install all npm dependencies.
• Launch Visual Studio Code in the project folder.
• Open your default browser to http://localhost:5173.
• Start the development servers for both the client and the server side.

You need the following installed for the quick installation:

• Git (version: 2.50.0 or higher recommended)
• Node.js (version: 22.17.0 or higher recommended)
• npm (version: 10.9.0 or higher recommended)
• Visual Studio Code (Optional)

Open your terminal and copy and paste the following code:

#!/usr/bin/env bash

# Strict Mode
# -e: Exit immediately if a command exits with a non-zero status.
# -o pipefail: The return value of a pipeline is the status of the last command
#    to exit with a non-zero status, or zero if no command exited with a
#    non-zero status.
# -u: Treat unset variables as an error when substituting.

set -eo pipefail
set -u

# --- Initial Setup ---
echo # Blank line for spacing
echo "Cloning repository..."
git clone https://github.com/homelab-alpha/npm-workspaces-template.git
cd npm-workspaces-template

echo # Blank line for spacing
echo "Running initialization script..."
./scripts/init.sh
# Re-evaluate shell's current directory to apply changes from init.sh
cd .

# --- OS-specific Command Setup ---
# Set commands based on the detected Operating System to ensure compatibility.
if [[ "$OSTYPE" == "darwin"* ]]; then # macOS
  SLEEP_CMD="sleep 5"
  OPEN_CMD="open"
elif [[ "$OSTYPE" == "msys" || "$OSTYPE" == "win32" ]]; then # Windows
  SLEEP_CMD="timeout /T 5 /NOBREAK >nul"
  OPEN_CMD="start"
else # Linux
  SLEEP_CMD="sleep 5"
  OPEN_CMD="xdg-open"
fi

# --- Execution Sequence ---
echo # Blank line for spacing
echo "Installing npm dependencies..."
npm install

# Launch Visual Studio Code if the 'code' command is available.
if command -v code &> /dev/null; then
  echo # Blank line for spacing
  echo "Launching Visual Studio Code..."
  code .
else
  echo # Blank line for spacing
  echo "Visual Studio Code 'code' command not found, skipping."
  eval "$SLEEP_CMD"
fi

echo # Blank line for spacing
echo "Opening application in browser at http://localhost:5173..."
$OPEN_CMD http://localhost:5173/
eval "$SLEEP_CMD"

echo # Blank line for spacing
echo "Starting development server... (Press Ctrl+C to stop)"
npm run dev

This project is licensed under the Apache License 2.0. See the LICENSE file for more details.