https://github.com/homelab-alpha/npm-workspaces-template
A boilerplate for npm workspaces. Perfect for kickstarting a well organized, scalable project environment with a clear folder structure.
https://github.com/homelab-alpha/npm-workspaces-template
boilerplate client-server full-stack javascript monorepo nodejs npm npm-workspaces starter template typescript vue web-development
Last synced: 2 months ago
JSON representation
A boilerplate for npm workspaces. Perfect for kickstarting a well organized, scalable project environment with a clear folder structure.
- Host: GitHub
- URL: https://github.com/homelab-alpha/npm-workspaces-template
- Owner: homelab-alpha
- License: apache-2.0
- Created: 2025-07-06T10:14:05.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2025-10-06T05:36:15.000Z (8 months ago)
- Last Synced: 2025-10-06T07:25:14.058Z (8 months ago)
- Topics: boilerplate, client-server, full-stack, javascript, monorepo, nodejs, npm, npm-workspaces, starter, template, typescript, vue, web-development
- Language: Shell
- Homepage:
- Size: 1.08 MB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
- Maintainers: MAINTAINERS.md
Awesome Lists containing this project
README
# npm Workspaces Template
[](https://github.com/homelab-alpha/npm-workspaces-template/actions/workflows/linting.yml)
[](https://github.com/homelab-alpha/npm-workspaces-template/actions/workflows/codeql.yml)
[](https://github.com/homelab-alpha/npm-workspaces-template/commits/main/)
[](https://github.com/homelab-alpha/npm-workspaces-template/tree/main?tab=readme-ov-file#npm-workspaces-template)
[](https://github.com/homelab-alpha/npm-workspaces-template/blob/main/CHANGELOG.md)
[](https://github.com/homelab-alpha/npm-workspaces-template/blob/main/CODE_OF_CONDUCT.md)
[](https://conventionalcommits.org)
[](https://github.com/semver/semver/blob/master/semver.md)
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
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
Local Development (npm Only)
Step 1: Start the development servers
Step 2: Access the application
Docker and Docker Compose
Building and Running the Application
Step 1: Build Docker Images
Step 2: Start the Application
Step 3: Access the Application
Step 4: Stop the Application and remove the container and network
Running Tests with Docker Compose
Step 1: Build the Docker image and run the tests in a container
Step 2: Clean up resources
Linting and Formatting
Checking Code Style
Format Code Style
Fixing Code Style
Contributing
Known Issues
Currently Being Addressed
Quick Installation
Prerequisites
Run the Quick script
License
## Project Progress
> [!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.
### To-Do List
- [ ] Create a final prerelease checklist.
#### Client
- [ ] Pending tasks (to be defined).
#### Docker
- [ ] Pending tasks (to be defined).
#### Server
- [ ] Pending tasks (to be defined).
#### Documentation
- [ ] Remove the **Caution** notice once the project reaches a stable phase.
- [ ] Create an `ROADMAP.md`
- [ ] Update the `CHANGELOG.md`
## Features
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.
## Getting Started
### Prerequisites
Ensure you have the following installed:
- [Git](https://git-scm.com/downloads) (version: 2.50.0 or higher recommended)
- [Node.js](https://nodejs.org/en/download/) (version: 22.17.0 or higher
recommended)
- [npm](https://www.npmjs.com/get-npm) (version: 10.9.0 or higher recommended)
- [Docker Desktop](https://www.docker.com/products/docker-desktop/) (includes
**Docker Engine** and **Docker Compose**)
### Using this Template
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](#contributing) section.
#### Step 1: Clone the repository
Open your terminal and run the following command:
```bash
git clone https://github.com/homelab-alpha/npm-workspaces-template.git
```
#### Step 2: Navigate to the project directory
Change into the newly cloned project directory:
```bash
cd npm-workspaces-template
```
#### Step 3: Initialize the project
> [!CAUTION]
>
> The `init.sh` script is designed exclusively for **Linux** environments.
> Support for **macOS** and **Windows** is planned for a future release.
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.
```bash
./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.
> [!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]
>
> Install the [Renovate GitHub App](https://github.com/apps/renovate) if not
> already installed. It will help you keep your dependencies up to date
> automatically.
#### Step 4: Install project dependencies
From the root directory of your project, install all required dependencies:
```bash
npm install
```
## Development
Once the project is set up, you can use the following commands for development,
testing, and deployment.
### Local Development (npm Only)
To run the project directly on your machine:
#### Step 1: Start the development servers
This command will start both the client (**Vite**) and server (**Express.js**)
in development mode.
```bash
npm run dev
```
#### Step 2: Access the application
The application should be accessible in your web browser at
[http://localhost:5173](http://localhost:5173).
## Docker and Docker Compose
> [!IMPORTANT]
>
> The provided Docker configurations (`compose.build.yml`, `compose.prod.yml`,
> `compose.test.yml`, and `Dockerfile`) are designed primarily for **local
> development and testing**. Additional modifications may be necessary for a
> full production deployment.
To get the project running locally using **Docker** and **Docker Compose**,
follow these steps:
### Building and Running the Application
Follow the steps below to build Docker images and run the application in a local
production-like environment.
#### Step 1: Build Docker Images
Use the build configuration file to create the necessary images:
```bash
docker compose --file docker/compose.build.yml build
```
#### Step 2: Start the Application
Start the production containers using:
```bash
docker compose --file docker/compose.prod.yml up
```
To run the containers in the background (detached mode), use:
```bash
docker compose --file docker/compose.prod.yml up --detach
```
#### Step 3: Access the Application
Once the containers are running, access the app at:
[http://localhost:5173](http://localhost:5173)
#### Step 4: Stop the Application and remove the container and network
To stop containers running in the **foreground**, press `CTRL+C`, then run:
```bash
docker compose --file docker/compose.prod.yml down
```
For containers running in **detached mode**, just run:
```bash
docker compose --file docker/compose.prod.yml down
```
This command stops and removes the container and network, ensuring a clean state
after use.
### Running Tests with Docker Compose
To execute the test suite inside a **Docker** container:
#### Step 1: Build the Docker image and run the tests in a container
```bash
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.
#### Step 2: Clean up resources
After the tests are completed, run the following command to remove the container
service (`npm-workspaces-template-test`) and its network.
```bash
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.
## Linting and Formatting
This project uses **ESLint** for code linting, **Prettier** for code and
Markdown file linting.
### Checking Code Style
To check for any linting or formatting issues across all workspaces and Markdown
files:
```bash
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.
### Format Code Style
To automatically fix any linting and formatting issues across all workspaces and
Markdown files:
```bash
npm run format
```
This command will run `format` for the `client` and `server` workspaces, and
`markdown:format` for all Markdown files.
### Fixing Code Style
To automatically fix most linting and formatting issues:
```bash
npm run lint
```
This command will run `lint` for both the `client` and `server` workspaces, and
then `markdown:lint` for all Markdown files.
## Contributing
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 bugfix
5. Submit a pull request from your branch to our `main` branch
For more detailed guidelines, please refer to the
[CODE OF CONDUCT](https://github.com/homelab-alpha/npm-workspaces-template/blob/main/CODE_OF_CONDUCT.md),
[CONTRIBUTING](https://github.com/homelab-alpha/npm-workspaces-template/blob/main/CONTRIBUTING.md),
and
[Code Style and Standards Guide](https://github.com/homelab-alpha/npm-workspaces-template/blob/main/CODE_STYLE_AND_STANDARDS_GUIDES.md)
files.
## Known Issues
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.
### Currently Being Addressed
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](https://github.com/homelab-alpha/npm-workspaces-template/issues/new/choose).
## Quick Installation
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](http://localhost:5173).
- Start the development servers for both the **client** and the **server** side.
### Prerequisites
You need the following installed for the quick installation:
- [Git](https://git-scm.com/downloads) (version: 2.50.0 or higher recommended)
- [Node.js](https://nodejs.org/en/download/) (version: 22.17.0 or higher
recommended)
- [npm](https://www.npmjs.com/get-npm) (version: 10.9.0 or higher recommended)
- [Visual Studio Code](https://code.visualstudio.com/Download) (Optional)
### Run the Quick script
Open your terminal and copy and paste the following code:
```bash
#!/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
```
> [!TIP]
>
> After completing the **Quick Installation**, your browser should automatically
> open to the application. You may need to refresh the page (using **F5** or
> **Ctrl+R**) to ensure the latest content is loaded; or if you encounter any
> issues, please open your web browser and navigate to
> [http://localhost:5173](http://localhost:5173) manually.
> [!NOTE]
>
> When using the **Quick Installation**, you may encounter extra logs at
> `Opening application in browser at http://localhost:5173...` in the terminal.
> These logs are from the browser and may include initial connection errors or
> additional messages when attempting to open `http://localhost:5173`. This is
> expected behavior, as the development server may not have fully started yet.
## License
This project is licensed under the **Apache License 2.0**. See the
[LICENSE](https://github.com/homelab-alpha/npm-workspaces-template/blob/main/LICENSE)
file for more details.