diff --git a/.env.development b/.env.development new file mode 100644 index 0000000..1b81fce --- /dev/null +++ b/.env.development @@ -0,0 +1,7 @@ +VITE_APP_API_URL=http://localhost:3000 +VITE_APP_ANOTHER_API_URL=http://localhost:3000 +VITE_APP_GRAPHQL_PROXY_ENDPOINT=https://graphqlzero.almansi.me +VITE_APP_REST_PROXY_ENDPOINT=https://jsonplaceholder.typicode.com +VITE_APP_SENTRY_DSN=project_dsn +VITE_APP_SENTRY_ENABLED=false +SENTRY_ENVIRONMENT=dev \ No newline at end of file diff --git a/.env.production b/.env.production new file mode 100644 index 0000000..1b81fce --- /dev/null +++ b/.env.production @@ -0,0 +1,7 @@ +VITE_APP_API_URL=http://localhost:3000 +VITE_APP_ANOTHER_API_URL=http://localhost:3000 +VITE_APP_GRAPHQL_PROXY_ENDPOINT=https://graphqlzero.almansi.me +VITE_APP_REST_PROXY_ENDPOINT=https://jsonplaceholder.typicode.com +VITE_APP_SENTRY_DSN=project_dsn +VITE_APP_SENTRY_ENABLED=false +SENTRY_ENVIRONMENT=dev \ No newline at end of file diff --git a/README.md b/README.md index 28063dc..5a31caf 100644 --- a/README.md +++ b/README.md @@ -1,90 +1,31 @@ - -## Base Mr. Milu: React.js - -### Index and features - -- [Vite](https://github.com/vitejs/vite) -- 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) -- [Apollo Client (GraphQL)](https://github.com/apollographql/apollo-client) -- [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) -- [react-i18next](docs/i18next.md) ([i18next react official documentation](https://react.i18next.com/)) -- [Development proxy server](docs/dev_proxy.md) -- [React Router 6](https://reactrouter.com/en/main) -- Sentry - -### Prerequisites - -This project uses the following packages - -- [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** - -In one terminal shell - -```shell -just dev -``` - -And in another shell - -```shell -just ioc-generate-watch -``` - -**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 - -``` -VITE_APP_API_URL=http://localhost:3000 -VITE_APP_ANOTHER_API_URL=http://localhost:3000 -VITE_APP_GRAPHQL_PROXY_ENDPOINT=https://graphqlzero.almansi.me -VITE_APP_REST_PROXY_ENDPOINT=https://jsonplaceholder.typicode.com -VITE_APP_SENTRY_DSN=project_dsn -VITE_APP_SENTRY_ENABLED=false -SENTRY_ENVIRONMENT=dev -``` +# React Base + +Milú React base project + +## Docs +- [Clean Architecture] (to include link to front.docs) +- [Commit Lint] (to include link to front.docs) +- [Craco](./docs/craco.md) +- [Dependencies](./docs/dependencies.md) +- [Development environment setup](./docs/dev-environment-setup.md) +- [Development proxy](./docs/dev-proxy.md) +- [Environment variables](./docs/environment-variables.md) +- [ErrorBoundary](./docs/error-boundary.md) +- [Internationalization](./docs/i18next.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ú \ No newline at end of file diff --git a/docs/comitlint.md b/docs/comitlint.md deleted file mode 100644 index 0fec6ae..0000000 --- a/docs/comitlint.md +++ /dev/null @@ -1,60 +0,0 @@ -## Commitlint - -### Conventional commits examples - -#### Commit message with description and breaking change footer - -```bash -feat: allow provided config object to extend other configs - -BREAKING CHANGE: `extends` key in config file is now used for extending other config files -``` - -#### Commit message with ! to draw attention to breaking change - -```bash -feat: allow provided config object to extend other configs -``` - -feat!: send an email to the customer when a product is shipped - -#### Commit message with scope and ! to draw attention to breaking change - -```bash -feat(api)!: send an email to the customer when a product is shipped - -###Commit message with both ! and BREAKING CHANGE footer -``` - -```bash -chore!: drop support for Node 6 - -BREAKING CHANGE: use JavaScript features not available in Node 6. -``` - -#### Commit message with no body - -```bash -docs: correct spelling of CHANGELOG -``` - -#### Commit message with scope - -```bash -feat(lang): add polish language -``` - -#### Commit message with multi-paragraph body and multiple footers - -```bash -fix: prevent racing of requests - -Introduce a request id and a reference to latest request. Dismiss -incoming responses other than from latest request. - -Remove timeouts which were used to mitigate the racing issue but are -obsolete now. - -Reviewed-by: Z -Refs: #123 -``` diff --git a/docs/craco.md b/docs/craco.md index dd33e2a..a9821d5 100644 --- a/docs/craco.md +++ b/docs/craco.md @@ -1,4 +1,4 @@ -## CRACO +# CRACO CRACO stands for: **Create React App Configuration Override**. This boilerplate is created with CRA to get all the benefits from `react-scripts`. The issue with CRA configured projects it's that, although they offer many out of the box diff --git a/docs/dependencies.md b/docs/dependencies.md new file mode 100644 index 0000000..cbf1a41 --- /dev/null +++ b/docs/dependencies.md @@ -0,0 +1,20 @@ +# Dependencies + +## Relevant used dependencies + +- [Vite](https://github.com/vitejs/vite) +- 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) +- [Apollo Client (GraphQL)](https://github.com/apollographql/apollo-client) +- [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) +- [react-i18next](docs/i18next.md) ([i18next react official documentation](https://react.i18next.com/)) +- [Development proxy server](docs/dev_proxy.md) +- [React Router 6](https://reactrouter.com/en/main) +- Sentry \ No newline at end of file diff --git a/docs/dev-environment-setup.md b/docs/dev-environment-setup.md new file mode 100644 index 0000000..19cccc2 --- /dev/null +++ b/docs/dev-environment-setup.md @@ -0,0 +1,34 @@ +# 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 + ``` + +4. Generate the GQL schemas. + + ```shell + just graphql-codegen + ``` \ No newline at end of file diff --git a/docs/dev_proxy.md b/docs/dev-proxy.md similarity index 97% rename from docs/dev_proxy.md rename to docs/dev-proxy.md index 92c8237..f77579c 100644 --- a/docs/dev_proxy.md +++ b/docs/dev-proxy.md @@ -1,4 +1,4 @@ -## Development Proxy +# Development Proxy Due to the nature of front end development and their tooling (hot reload, bundlers, dependency installation) most of the time our development server will run better in our local machines; in comparison with a docker environment. diff --git a/docs/environment-variables.md b/docs/environment-variables.md new file mode 100644 index 0000000..c96b189 --- /dev/null +++ b/docs/environment-variables.md @@ -0,0 +1,30 @@ +# Environment variables + +> ℹ️ .env variables are loaded automatically by Vite. Refer to this documentation for more information. [Loading Environment Variables](https://vitejs.dev/guide/env-and-mode#env-files). + +> 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 | +| --------------------------------- | ----------- | --------- | ------ | ------------------------- | ----------------------- | ---------------------------------- | ---------------------------------------------------------------------- | +| `VITE_APP_API_URL` | DevOps | `string` | No | `DEFAULT` | `http://localhost:3000` | GQL API URL URL | +| `VITE_APP_ANOTHER_API_URL` | DevOps | `string` | No | `DEFAULT` | `http://localhost:3000` | REST API URL URL | - | +| `VITE_APP_GRAPHQL_PROXY_ENDPOINT` | DevOps | `string` | No | `REQUIRED-IN-RELEASE-ENV` | - | GQL Proxy Endpoint URL | - | +| `VITE_APP_REST_PROXY_ENDPOINT` | DevOps | `string` | No | `REQUIRED-IN-RELEASE-ENV` | - | REST Proxy Endpoint DSN | | +| `VITE_APP_SENTRY_DSN` | DevOps | `string` | No | `REQUIRED-IN-RELEASE-ENV` | - | Sentry DSN | [Sentry DSN](https://docs.sentry.io/concepts/key-terms/dsn-explainer/) | +| `VITE_APP_SENTRY_ENABLED` | DevOps | `boolean` | No | `FEATURE-FLAG` | - | Enables/Disables Sentry monitoring | - | + +## 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 \ No newline at end of file diff --git a/docs/error_boundary.md b/docs/error-boundary.md similarity index 97% rename from docs/error_boundary.md rename to docs/error-boundary.md index 459dadf..edae30f 100644 --- a/docs/error_boundary.md +++ b/docs/error-boundary.md @@ -1,4 +1,4 @@ -## Error boundaries +# Error boundaries To avoid ui errors breaking the app and make it unusable we are going to implement error boundaries at page level (in our routes object). This way we can guarantee if a page breaks the user can still navigate it's way out and the application diff --git a/docs/justfile-commands.md b/docs/justfile-commands.md new file mode 100644 index 0000000..fae6b70 --- /dev/null +++ b/docs/justfile-commands.md @@ -0,0 +1,27 @@ +# React Base 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 vite development server. +- `just debug`: Starts the vite debug server. +- `just build`: Builds the vite application. +- `just preview`: Builds the vite application in preview mode. +- `just clean`: Cleans the vite cache +- `just start`: Starts the server for the built Next.js application. +- `just prettier-fix:`: Runs 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 graphql-codegen`: Downloads schema and generates corresponding ts types. +- `just e2e-run`: Runs E2E tests. +- `just e2e-open`: Runs E2E tests UI. +- `just commit`: Commit files using commitlint. +- `just nvm exec {{command}}`: Proxies a command through nvm. Replace `{{command}}` with the desired command to execute. \ No newline at end of file diff --git a/docs/run-development-server.md b/docs/run-development-server.md new file mode 100644 index 0000000..8222148 --- /dev/null +++ b/docs/run-development-server.md @@ -0,0 +1,6 @@ +# Run development server + +```shell +just ioc-generate-watch # in one terminal +just dev # in another +``` \ No newline at end of file diff --git a/docs/run-production-build.md b/docs/run-production-build.md new file mode 100644 index 0000000..5aecd40 --- /dev/null +++ b/docs/run-production-build.md @@ -0,0 +1,25 @@ +# Run production build + +First generate the dependency injection files: +```shell +just ioc-generate +``` + +Then generate the graphql types: +```shell +just graphql-codegen +``` + +Next run a production build: + +```shell +just build +``` + +Finally execute the `vite preview` server: + +```shell +just preview +``` + +This command uses under the hood the `vite preview` command. For more information refer to [Deploying a Static Site](https://vitejs.dev/guide/static-deploy.html#deploying-a-static-site) documentation where `vite preview` is explained. \ No newline at end of file diff --git a/justfile b/justfile index f3dc012..119ec66 100644 --- a/justfile +++ b/justfile @@ -51,7 +51,7 @@ e2e-run: e2e-open: ./nvm_exec.sh pnpm e2e:open -# Opens E2E tests UI +# Commits changes using commitlint. commit: ./nvm_exec.sh pnpm commit