Merge pull request #22 from fac-32/feat/dev-environment-consistency

feat: Add standardised development environment

Author: MariShopen

.dockerignore

@@ -0,0 +1,24 @@
+# Dependencies
+node_modules
+dist
+
+# Environment files
+.env
+.env.*
+!/.env.example
+
+# Git
+.git
+
+# Logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Editor directories and files
+.idea
+.vscode
+*.suo
+*.ntvs*
+*.njsproj
+*.sln

.nvmrc

@@ -0,0 +1 @@
+v20

Containerfile

@@ -0,0 +1,20 @@
+# Use a more secure, slim version of the Node.js 20 image as a parent image
+FROM node:20-slim
+
+# Set the working directory
+WORKDIR /app
+
+# Copy package.json and package-lock.json to the working directory
+COPY package*.json ./
+
+# Install project dependencies
+RUN npm install
+
+# Copy the rest of the application's source code from your host to your image filesystem.
+COPY . .
+
+# Make port 5173 available to the world outside this container
+EXPOSE 5173
+
+# Run the app when the container launches
+CMD ["npm", "run", "dev", "--", "--host"]

PIPELINE.md

@@ -0,0 +1,83 @@
+# CI/CD Pipeline Best Practices ⚙️
+
+This document outlines the best practices for our CI/CD pipeline to ensure consistent, reliable, and efficient builds.
+
+## Overview 🌎
+
+The primary goal of our CI/CD pipeline is to automate the process of building, testing, and deploying our application. Adhering to these guidelines is crucial for maintaining a stable and predictable development workflow.
+
+## Key Principles 🔑
+
+- **Consistency:** Every build should be consistent, regardless of who triggers it or when.
+- **Reproducibility:** We must be able to reproduce any build at any time. This is critical for debugging and for ensuring that what we test is what we deploy.
+- **Speed:** A fast pipeline means faster feedback for developers.
+
+## Dependency Management 🖇️
+
+Proper dependency management is the foundation of a reliable CI/CD pipeline.
+
+### The Role of `package.json` and `package-lock.json` 📦
+
+- **`package.json`**: Lists the dependencies your project needs, often with a version range (e.g., `^1.2.3`). This file describes the _intended_ dependencies.
+- **`package-lock.json`**: Records the _exact_ version of every dependency that was installed, including sub-dependencies. This file ensures that you get the same dependency tree every single time. **This file must be committed to the repository.**
+
+### `npm install` vs. `npm ci`
+
+This is the most important distinction for our workflow.
+
+- **`npm install`**:
+  - Use this command for **local development when you need to add or update dependencies**.
+  - It may update your `package-lock.json` file based on the version ranges in `package.json`.
+  - **NEVER use `npm install` (without arguments) in the CI/CD pipeline.**
+
+- **`npm ci`** ("Clean Install"):
+  - This is the **ONLY command that should be used to install dependencies in the CI/CD pipeline**.
+  - It installs dependencies directly from `package-lock.json`, ignoring `package.json`.
+  - It guarantees reproducible builds because it always installs the exact same dependency versions.
+  - It's generally faster than `npm install`.
+  - It starts by deleting the `node_modules` directory to ensure a clean installation.
+
+## Workflow for Managing Dependencies
+
+### Local Development Workflow
+
+1. **To add a new dependency:**
+
+   ```bash
+   npm install <package-name>
+   ```
+
+   For a development dependency (e.g., a testing library):
+
+   ```bash
+   npm install <package-name> --save-dev
+   ```
+
+2.**Commit changes:** After adding or updating dependencies, commit both the `package.json` and the updated ``package-lock.json` files.
+
+```bash
+git add package.json package-lock.json
+git commit -m "feat: Add <package-name> dependency"
+```
+
+### CI/CD Pipeline Workflow
+
+1.**Checkout code:** The pipeline will check out the latest version of the code from the repository.
+
+2.**Install dependencies:** The pipeline must use `npm ci` to install dependencies.
+
+```yaml
+# Example step in a GitHub Actions workflow
+- name: Install Dependencies
+  run: npm ci
+```
+
+This ensures that the pipeline uses the exact dependency versions that you tested with locally.
+
+## Best Practices Summary
+
+- **Always** commit your `package-lock.json` file.
+- **Always** use `npm ci` in the CI/CD pipeline to install dependencies.
+- **Only** use `npm install <package-name>` locally to add or update dependencies.
+- **Regularly** update your dependencies locally to get the latest features and security patches, and commit the updated `package-lock.json`.
+- Ensure your `package.json` and `package-lock.json` files are in sync before pushing your changes. `npm ci` will fail if they are not, which is a good thing.

README.md

@@ -11,6 +11,36 @@ Currently, two official plugins are available:
 
 The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
 
+## Development Environment
+
+This project requires **Node.js version 20 or higher**. To ensure a consistent development environment, we have included an `.nvmrc` file.
+
+If you are using [Node Version Manager (nvm)](https://github.com/nvm-sh/nvm), you can switch to the correct Node.js version by running the following command in the project root:
+
+```bash
+nvm use
+```
+
+This will automatically read the `.nvmrc` file and set your Node.js version accordingly.
+
+## Containerized Development with Podman
+
+For the most consistent development experience across all operating systems, you can use Podman to run the application in a container.
+
+First, build the container image:
+
+```bash
+podman build -t keycv-interface .
+```
+
+Then, run the container:
+
+```bash
+podman run -p 5173:5173 -v ./src:/app/src keycv-interface
+```
+
+This will start the Vite development server, and you can access the application at `http://localhost:5173`. The `-v ./src:/app/src` flag mounts the `src` directory into the container, allowing for hot-reloading when you make changes to your code.
+
 ## Linting
 
 To run the lint check in this project before pushing your repository, execute the following command: