Merge pull request #21 from mrmilu/feature/IFMD-23-docs-standarization

docs: modify docs to comply with new standard
mrmilu · Jul 5, 2024 · f646c8e · f646c8e
2 parents edaa0c3 + 2bd5fd3
commit f646c8e
Show file tree

Hide file tree

Showing 13 changed files with 179 additions and 170 deletions.
diff --git a/.env.development b/.env.development
@@ -0,0 +1,9 @@
+NEXT_PUBLIC_API_URL=http://localhost:3000
+NEXT_PUBLIC_REST_PROXY_ENDPOINT=https://jsonplaceholder.typicode.com
+NEXT_PUBLIC_SENTRY_DSN=project_dsn
+NEXT_PUBLIC_SENTRY_ENABLED=false
+SENTRY_ENVIRONMENT=dev
+SENTRY_URL=https://sentry.mrmilu.com
+SENTRY_ORG=mrmilu
+SENTRY_PROJECT=project-name
+SENTRY_AUTH_TOKEN=sentry-user-auth-token
diff --git a/.env.production b/.env.production
@@ -0,0 +1,9 @@
+NEXT_PUBLIC_API_URL=https://jsonplaceholder.typicode.com
+NEXT_PUBLIC_REST_PROXY_ENDPOINT=https://jsonplaceholder.typicode.com
+NEXT_PUBLIC_SENTRY_DSN=project_dsn
+NEXT_PUBLIC_SENTRY_ENABLED=false
+SENTRY_ENVIRONMENT=dev
+SENTRY_URL=https://sentry.mrmilu.com
+SENTRY_ORG=mrmilu
+SENTRY_PROJECT=project-name
+SENTRY_AUTH_TOKEN=sentry-user-auth-token
diff --git a/.gitignore b/.gitignore
@@ -33,9 +33,7 @@ yarn-debug.log*
 yarn-error.log*
 
 # local env files
-.env.development.local
-.env.test.local
-.env.production.local
+.env*.local
 
 # vercel
 .vercel
diff --git a/README.md b/README.md
@@ -1,103 +1,28 @@
-## Base Mr. Milu: Next.js
-
-### Index and features
-
-- Clean architecture
-- Dependency Injection ([Inversify](https://github.com/inversify/InversifyJS))
-- Typescript
-- [Class transformers](https://github.com/typestack/class-transformer)
-- [Zustand](https://github.com/pmndrs/zustand)
-- [Commitlint](docs/comitlint.md) (with [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) config)
-- [Vanilla extract](https://vanilla-extract.style/)
-- ESLint (with TypeScript config)
-- Prettier
-- [Error boundary](docs/error_boundary.md)
-- [next-intl](https://next-intl-docs.vercel.app/)
-- Development proxy through Pages API Routes
-- Sentry
-
-### Prerequisites
-
-This project uses the following packages, please install them first.
-
-- [nvm](https://github.com/nvm-sh/nvm) (Node version manager)
-- [Just](https://just.systems/man/en/chapter_4.html) (For justfile usage)
-
-Run the following command to install the node version declared in the `.nvmrc`
-file for this project:
-
-```shell
-nvm install
-```
-
-Finally, enable [corepack](https://github.com/nodejs/corepack) so the correct
-version of pnpm is used.
-
-```shell
-just corepack-enable
-```
-
-### First steps
-
-**Install dependencies**
-
-```shell
-just install-deps
-```
-
-**Run project**
-
-```shell
-just ioc-generate-watch # in one terminal
-just dev # in another
-```
-
-**See a list of available commands**
-
-```shell
-just
-```
-
-**Proxy commands through nvm**
-
-```shell
-just nvm-exec "pnpm add @front_web_mrmilu/hooks"
-```
-
-### Environment variables
-
-Create a `.env.development.local` file with your environment variables with the following defaults for dev server
-
-```
-NEXT_PUBLIC_API_URL=http://localhost:3000
-NEXT_PUBLIC_REST_PROXY_ENDPOINT=https://jsonplaceholder.typicode.com
-NEXT_PUBLIC_SENTRY_DSN=project_dsn
-NEXT_PUBLIC_SENTRY_ENABLED=false
-SENTRY_ENVIRONMENT=dev
-SENTRY_URL=https://sentry.mrmilu.com
-SENTRY_ORG=mrmilu
-SENTRY_PROJECT=project-name
-SENTRY_AUTH_TOKEN=sentry-user-auth-token
-```
-
-Also create a `.env.production.local` file with your environment variables with the following defaults for production
-build
-
-```
-NEXT_PUBLIC_API_URL=https://jsonplaceholder.typicode.com
-#NEXT_PUBLIC_SENTRY_DSN=project_dsn
-NEXT_PUBLIC_SENTRY_ENABLED=false
-SENTRY_ENVIRONMENT=dev
-SENTRY_URL=https://sentry.mrmilu.com
-SENTRY_ORG=mrmilu
-SENTRY_PROJECT=project-name
-SENTRY_AUTH_TOKEN=sentry-user-auth-token
-```
-
-### CI/CD build commands
-
-```shell
-pnpm install
-pnpm ioc-generate
-pnpm build
-```
+# Next.js Base
+
+Milú Next.js base project
+
+## Docs
+- [Clean Architecture] (to include link to front.docs)
+- [Commit Lint] (to include link to front.docs)
+- [Dependencies](./docs/dependencies.md)
+- [Development environment setup](./docs/dev-environment-setup.md)
+- [Environment variables](./docs/environment-variables.md)
+- [ErrorBoundary](./docs/error-boundary.md)
+- [Justfile Commands](./docs/justfile-commands.md)
+- [Run development server](./docs/run-development-server.md)
+- [Run production build](./docs/run-production-build.md)
+
+## Versions
+
+This project uses the following versions and has been tested in this context
+(please check if that works with yours):
+
+| Service    | Version  | Usage              |
+|------------|----------|--------------------|
+| `node`     | `20.x`   | `*`                |
+| `pnpm`     | `9.4.0`  | `package.json`     |
+| `just`     | `1.x`    | `justfile`         |
+
+### Authors
+By Milú
diff --git a/docs/comitlint.md b/docs/comitlint.md
diff --git a/docs/dependencies.md b/docs/dependencies.md
@@ -0,0 +1,15 @@
+# Dependencies
+
+### Relevant used dependencies
+
+- Dependency Injection ([Inversify](https://github.com/inversify/InversifyJS))
+- Typescript
+- [Class transformers](https://github.com/typestack/class-transformer)
+- [Zustand](https://github.com/pmndrs/zustand)
+- [Commitlint](docs/comitlint.md) (with [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) config)
+- [Vanilla extract](https://vanilla-extract.style/)
+- ESLint (with TypeScript config)
+- Prettier
+- [Error boundary](docs/error_boundary.md)
+- [next-intl](https://next-intl-docs.vercel.app/)
+- Sentry
diff --git a/docs/dev-environment-setup.md b/docs/dev-environment-setup.md
@@ -0,0 +1,28 @@
+# Dev environment setup
+
+## Requirements
+These are the requirements to run a development environment:
+
+- [nvm](https://github.com/nvm-sh/nvm) (Node version manager)
+- [just](https://github.com/casey/just)
+
+## Steps
+
+1. Run the following command to install the node version declared in the `.nvmrc` file for this project:
+
+    ```shell
+    nvm install
+    ```
+
+2. Enable [corepack](https://github.com/nodejs/corepack) so the correct
+version of [pnpm](https://pnpm.io/motivation) is used.
+
+    ```shell
+    just corepack-enable
+    ```
+
+3. Install the project dependencies.
+
+    ```shell
+    just install-deps
+    ```
diff --git a/docs/environment-variables.md b/docs/environment-variables.md
@@ -0,0 +1,33 @@
+# Environment variables
+
+> ℹ️ .env variables are loaded automatically by Next.js. Refer to this documentation for more information. [Loading Environment Variables](https://nextjs.org/docs/app/building-your-application/configuring/environment-variables#loading-environment-variables).
+
+> Good to know: `.env`, `.env.development`, and `.env.production` files should be included in your repository as they define defaults. .env*.local should be added to .gitignore, as those files are intended to be ignored. .env.local is where secrets can be stored.
+
+## Values
+
+| Key                               | Responsible | Type      | Secret | Policy                    | Default value              | Description                                                                                                                                                         | Docs                                                                                                        |
+| --------------------------------- | ----------- | --------- | ------ | ------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `NEXT_PUBLIC_API_URL`             | DevOps      | `string`  | No     | `DEFAULT`                 | `next_base.dev.mrmilu.com` | NextJS App URL                                                                                                                                                      | -                                                                                                           |
+| `NEXT_PUBLIC_REST_PROXY_ENDPOINT` | DevOps      | `string`  | No     | `REQUIRED-IN-RELEASE-ENV` | -                          | Proxy Endpoint URL                                                                                                                                                  | -                                                                                                           |
+| `NEXT_PUBLIC_SENTRY_DSN`          | DevOps      | `string`  | No     | `REQUIRED-IN-RELEASE-ENV` | -                          | Sentry DSN                                                                                                                                                          | [Sentry DSN](https://docs.sentry.io/concepts/key-terms/dsn-explainer/)                                      |
+| `NEXT_PUBLIC_SENTRY_ENABLED`      | DevOps      | `boolean` | No     | `FEATURE-FLAG`            | -                          | Enables/Disables Sentry monitoring                                                                                                                                  | -                                                                                                           |
+| `SENTRY_URL`                      | DevOps      | `string`  | No     | `REQUIRED-IN-RELEASE-ENV` | -                          | The base URL of your Sentry instance.                                                                                                                               | [Sentry Webpack Plugin Options (url)](https://www.npmjs.com/package/@sentry/webpack-plugin#url)             |
+| `SENTRY_ORG`                      | DevOps      | `string`  | No     | `REQUIRED-IN-RELEASE-ENV` | -                          | The slug of the Sentry organization associated with the app.                                                                                                        | [Sentry Webpack Plugin Options (org)](https://www.npmjs.com/package/@sentry/webpack-plugin#org)             |
+| `SENTRY_PROJECT`                  | DevOps      | `string`  | No     | `REQUIRED-IN-RELEASE-ENV` | -                          | The slug of the Sentry project associated with the app.                                                                                                             | [Sentry Webpack Plugin Options (project)](https://www.npmjs.com/package/@sentry/webpack-plugin#project)     |
+| `SENTRY_AUTH_TOKEN`               | DevOps      | `string`  | Yes    | `REQUIRED-IN-RELEASE-ENV` | -                          | The authentication token to use for all communication with Sentry. Can be obtained from https://sentry.io/orgredirect/organizations/:orgslug/settings/auth-tokens/. | [Sentry Webpack Plugin Options (authToken)](https://www.npmjs.com/package/@sentry/webpack-plugin#authtoken) |
+
+
+## Policies
+- `DEFAULT`: This environment variable has a default value that works on most common usages
+- `REQUIRED`: This environment variable must be set, otherwise the application will not start throwing an exception
+- `REQUIRED-IN-RELEASE-ENV`: This environment variable must be set in release environments, the application will start but won't comply requirements: security, functionality, integration, performance, etc
+- `FEATURE-FLAG`: This environment variable changes a feature behavior 
+- `DEPRECATED`: Deprecated variables, see deprecated variables section
+
+## Types
+- `boolean`: string variable containing a boolean value 
+- `string`: string variable
+- `fs_path`: string variable containing a path in the file system
+- `email`: string variable containing an email
+- `string-list-by-comma`: list string values extracted by: split (using `,` as the separator) and trim
diff --git a/docs/error_boundary.md → docs/error-boundary.md b/docs/error_boundary.md → docs/error-boundary.md
diff --git a/docs/justfile-commands.md b/docs/justfile-commands.md
@@ -0,0 +1,21 @@
+# Justfile Commands 🦀 🚀
+
+Run `just` to display the list of available commands.
+
+## What is just?
+
+`just` is a handy way to save and run project-specific commands. Commands, called recipes, are stored in a file called `justfile` with syntax inspired by `make`.
+
+## Commands List
+
+- `just corepack-enable`: Enables Corepack in Node.js.
+- `just install-deps`: Installs the dependencies listed in the project's package.json.
+- `just dev`: Starts the Next.js development server.
+- `just build`: Builds the Next.js application.
+- `just start`: Starts the server for the built Next.js application.
+- `just fix`: Runs linting and formatting.
+- `just ioc-generate`: Generates Inversify bindings.
+- `just ioc-generate-watch`: Generates Inversify bindings and watches for changes.
+- `just commit`: Commits changes using commitlint
+- `just nvm exec {{command}}`: Proxies a command through nvm. Replace `{{command}}` with the desired command to execute.
+
diff --git a/docs/run-development-server.md b/docs/run-development-server.md
@@ -0,0 +1,5 @@
+# Run development server
+
+```shell
+just ioc-generate-watch # in one terminal
+just dev # in another
diff --git a/docs/run-production-build.md b/docs/run-production-build.md
@@ -0,0 +1,26 @@
+# Run production build
+
+> ⚠️ You must have an `.env.production.local` in order to build a production build.
+
+First generate the dependency injection files:
+```shell
+just ioc-generate
+```
+
+Next run a production build:
+
+```shell
+just build
+```
+
+Finally execute Next.js server:
+
+- Default Next.js build
+    ```shell
+    just start
+    ```
+- Standalone build (output: standalone)
+    ```shell
+    node .next/standalone/server.js
+    ```
+
diff --git a/justfile b/justfile
@@ -24,14 +24,14 @@ fix:
     ./nvm_exec.sh pnpm lint
     ./nvm_exec.sh pnpm prettier-fix
 
-# Generate inversify bindings (watch execution)
-ioc-generate-watch:
-    ./nvm_exec.sh pnpm ioc-generate --watch
-
 # Generate inversify bindings
 ioc-generate:
     ./nvm_exec.sh pnpm ioc-generate
 
+# Generate inversify bindings (watch execution)
+ioc-generate-watch:
+    ./nvm_exec.sh pnpm ioc-generate --watch
+
 # Commit
 commit:
     ./nvm_exec.sh pnpm commit