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.
Table of Contents (click to expand)
npm Workspaces Template
Project Progress
To-Do List
Client
Docker
Server
Documentation
Script Development
Features
Getting Started
Prerequisites
Using this Template
Step 1: Clone the repository
Step 2: Navigate to the project directory
Step 3: Initialize the project
Step 4: Install project dependencies
Development
Available Commands
Local Development (npm Only)
Step 1: Start the development servers
Step 2: Access the application
Local Development (with Docker Compose)
Step 1: Navigate to the `docker` directory
Step 2: Start the development environment
Step 3: Access the application
Running Tests (with Docker Compose)
Step 1: Navigate to the `docker` directory
Step 2: Run the tests
Production Deployment (with Docker Compose)
Step 1: Navigate to the `docker` directory
Step 2: Start the production service
Linting and Formatting
Checking Code Style
Fixing Code Style
Contributing
Known Issues
Currently Being Addressed
License
Warning
Status: Work in Progress (WIP)
This project is currently under active development. Its structure, features, and content are subject to change frequently and without notice. At this time, contributions are not being accepted. Community contributions will be welcomed once the project reaches a more stable state.
- Create a final pre-release checklist.
- Pending tasks (to be defined).
- Create base Dockerfile.
- Set up Docker Compose files:
-
docker-compose.build.ymlfor building. -
docker-compose.prod.ymlfor production. -
docker-compose.test.ymlfor testing.
-
- Validate Dockerfile builds and functions correctly.
- Test all Docker Compose files for intended behavior.
- Implement and verify the full containerized build & deploy workflow.
- Set up core linting tools.
- Configure ESLint for JavaScript/TypeScript standards.
- Configure Prettier for consistent code formatting.
- Write detailed usage and setup instructions for
init.sh. - Finalize and update Step 3: Prepare the npm workspaces once
init.shis complete. - Expand documentation for Docker setup, usage, and environment-specific notes.
- Remove the Caution notice once the project reaches a stable phase.
- Remove the Caution notice once the Docker & Containerization setup is fully functional.
- Develop
init.shfor automated project setup and configuration. - Add clear and thorough inline documentation within
init.sh. - Apply shell scripting standards (shellcheck compliance).
- Test script functionality across various environments (Linux, etc.).
- TODO comments.
This template offers the following key features:
- npm Workspaces: Efficiently manages multi-package repositories.
- Automated Project Setup (Coming Soon): 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.
Note
These steps are for creating a new project. If you want to contribute to this template itself, please see the Contributing section.
Open your terminal and run the following command:
git clone https://github.com/homelab-alpha/npm-workspaces-template.gitChange into the newly cloned project directory:
cd npm-workspaces-templateWarning
Status: Work in Progress (WIP)
The initialization script is currently functional, but still under active development. New features and functionality will be added over time, and existing elements may change without prior notice.
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.
./init.shThis script will guide you through the following:
- Removing existing Git history: The
.gitdirectory 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.jsonand Docker Compose files.
Important
Essential: Verify Project Setup: After initialization, it is crucial to review and if necessary adjust project documentation and configuration files to align with your specific project requirements.
Note
You need to install the Renovate GitHub App if not already installed. It will help you keep your dependencies up to date automatically.
From the root directory of your project, install all required dependencies:
npm installOnce the project is set up, you can use the following commands for development, testing, and deployment.
- Local Development (npm Only)
- Local Development (with Docker Compose)
- Running Tests (with Docker Compose)
- Production Deployment (with Docker Compose)
- Linting and Formatting
To run the project directly on your machine without Docker:
This command will start both the client (Vite) and server (Express.js) in development mode.
npm run devThe application should be accessible in your web browser at http://localhost:5173.
⬆️ Go Back to Available Commands
Caution
The compose.build.yml, compose.prod.yml, compose.test.yml, and
Dockerfile for local development are currently untested and may/will not
work as expected. Use with caution.
To get the project up and running locally using Docker Compose for development:
cd dockerThis command will build the Docker image (if it doesn't exist or changes are detected) and start the containers, mounting your local code for live reloading.
docker compose --file compose.build.yml up --buildAlternatively, for detached mode:
docker compose --file compose.build.yml up --build --detachThe application should be accessible in your web browser at http://localhost:5173.
⬆️ Go Back to Available Commands
To execute project tests within a Docker container:
cd dockerThis command will build the test image and execute the configured test command
(e.g., npm run test --workspace=server). The container will exit after tests
are complete.
docker compose --file compose.test.yml up --build --abort-on-container-exit⬆️ Go Back to Available Commands
For deploying the application using a pre-built image from a container registry:
cd dockerThis command will pull the specified Docker image (if not already present) and run it in production mode.
docker compose --file compose.prod.yml up --detach⬆️ Go Back to Available Commands
This project uses ESLint for code linting, Prettier for code formatting, and Markdownlint for Markdown file linting.
To check for any linting or formatting issues across all workspaces and Markdown files:
npm run format:checkThis command will run format:check for both the client and server
workspaces, and then markdown:format:check for all Markdown files.
To automatically fix most linting and formatting issues:
npm run lintThis command will run lint for both the client and server workspaces, and
then markdown:lint for all Markdown files.
⬆️ Go Back to Available Commands
This repository serves as a template. If you want to contribute to the template's development, please follow these steps:
- Fork the repository
- Clone your forked repository:
git clone https://github.com/your-username/npm-workspaces-template.git - Install the dependencies
npm install - Create a new branch for your feature or bug fix
- Submit a pull request from your branch to our
mainbranch
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.
Last updated: July 16, 2025
This project is licensed under the Apache License 2.0. See the LICENSE file for more details.
![@renovate[bot]](https://avatars.githubusercontent.com/in/2740?s=64&v=4){kind=small}