Welcome to the monorepo for our new recipe application!! This is intended to be an introductory guide to help you get started with the project, including setting up your development environment, running the application, and deploying it to production.
The project is structured as a monorepo. This means all code related to our fullstack application is contained here in this single repository. The monorepo is organized into two main directories:
frontend: Contains the frontend code for the application, built with React and TypeScript via Vite. It includes the user interface and client-side logic.backend: Contains the backend code for the application, built with Go. It includes the API and database logic.
If we were using TypeScript for the backend too, we could share types between the applications for example, but here the main reason we've chosen a monorepo is to simplify versioning and deployment. This way, we can ensure that the frontend and backend are always in sync with each other.
In the root directory (the base directory), you may notice a few other files and directories:
.editorconfig: Configuration for maintaining consistent coding styles across different editors and IDEs. It specifies settings such as indentation, line endings, and character encoding. However, this is not strictly necessary for the project to work, and you can choose to ignore it if you prefer. We have additional linters that take precedence over this file, so you can safely ignore it in favor of the other linters..gitignore: Specifies files and directories that should be ignored by Git. It helps keep the repository clean by excluding unnecessary files.README.md: Documentation for the project. It provides an overview of the project, instructions for setting up the development environment, and other important information (it's what you're reading right now!).package.json: Contains metadata about the project, including dependencies, scripts, and other configurations. It is used by Node.js and npm to manage the project's packages and scripts. We have configured this file to include scripts for running both the frontend and backend applications, as well as other useful commands.package-lock.json: Automatically generated when you install packages using npm. It contains a snapshot of the exact versions of the dependencies installed in your project. It ensures that the same versions are used when the project is installed on different machines or environments. Do not edit this file manually; it is managed by npm.
See the Frontend Structure and Backend Structure sections for more details on the specific files and directories within the frontend and backend directories.
To get started with the project, you need to set up your development environment. This includes installing the necessary tools and dependencies to run the frontend and backend applications.
To run the frontend application, you need to have Node.js installed on your machine. You can download and install Node.js from the official website: Node.js. Just get the latest LTS version, we shouldn't have to worry about versioning issues, but if you do, please let me know. After installing Node.js, you can verify the installation by running the following commands in your terminal (make sure its a new session from after installing Node.js):
node -v
npm -vTo run the backend application, you need to have Go installed on your machine. You can download and install Go from the official website: Go. Like Node.js, just get the latest LTS version, we shouldn't have to worry about versioning issues, but if you do, please let me know. After installing Go, you can verify the installation by running the following command in your terminal (make sure its a new session from after installing Go):
go versionDuring development, .env files are used to store environment variables for both the frontend and backend applications. These files are not included in the repository for security reasons, but you can create them yourself based on the provided .env.example files. Currently, only the backend application uses any and it's only the port number, so you can ignore this for now.
The .env files are used to store sensitive information such as API keys, database connection strings, and other configuration settings that should not be shared publicly.
Click the large green "<> Code" button on the top right of the files in this page. Copy the HTTPS link, if you have an SSH key you can use the SSH version; you can learn more about that here. Head to the directory you want to clone the app into and type git clone link. Now you can go into the directory and follow the next steps.
To run the application, you must first install the dependencies for both the frontend and backend applications. You can do this by running the following commands in the root directory of the project:
npm installThis can be shortened to npm i if you prefer.
This will install all the dependencies listed in the root package.json file, then install the dependencies for the frontend and backend applications.
If you want to see how that works, open the package.json file in the root directory and look for the scripts section. You will see a script called postinstall that runs after npm install is finished.
After installing the dependencies, you can run the frontend and backend applications simultaneously using the following command:
npm run devThis command will start both the frontend and backend applications in development mode. The frontend application will be served on http://localhost:5173 by default, and the backend application will be served on http://localhost:8000 by default. You can access the frontend application in your web browser by navigating to http://localhost:5173, and the backend API will be available at http://localhost:8000. Vite will automatically reload in this development mode when you make changes to the frontend code, and the Go server will automatically re-compile and restart when you make changes to the backend code.
We use concurrently to easily run multiple flows in parallel for both the frontend and backend. Here's the important scripts you can run in the root directory of the project:
npm run dev: This command starts both the frontend and backend applications in development mode. The frontend will be served onhttp://localhost:5173, and the backend will be served onhttp://localhost:8000.npm run build: This command builds the frontend application for production. This will likely be seldom used in favor of docker handling this for you.npm run lint: This command runs the linter for both the frontend and backend applications. It checks the code for style and formatting issues and reports any errors or warnings.npm run format: This command formats the code for both the frontend and backend applications using Prettier. It automatically applies consistent formatting to the code based on the configuration specified in the.prettierrc.jsonfile.
All of the above commands have backend: and frontend: prefix versions to run them separately. e.g. npm run frontend:dev will only run the frontend application in development mode, and npm run backend:dev will only run the backend application in development mode. Do this if you are running into issues with a specific application and want to isolate the problem (especially with linting and formatting).
npm run postinstall: This command runs afternpm installis finished. It installs the dependencies for the frontend and backend applications. You can run this command manually if you want to install the dependencies without running the entirenpm installprocess.
If on vscode, install the Go, TypeScript, ESLint, and Prettier extensions for the frontend application and the Go extension for the backend application. This will help you catch any linting or formatting issues before you commit your code, making it easier to maintain a clean and consistent codebase.
For the Go extension, configure Go: Lint Tool in your settings to use golangci-lint as the linter. This will help you catch any linting or formatting issues before you commit your code, making it easier to maintain a clean and consistent codebase. ESLint and Prettier shouldn't need any configuration, just install the extensions and they will work out of the box.
We use ESLint and Prettier for the frontend application and GolangCI-Lint for the backend application. These tools help maintain consistent coding styles and catch potential issues in the code. You can set up your IDE to automatically run these linters when you save your files. Most modern IDEs have built-in support for these tools or have plugins available to integrate them into your workflow.
If you're using a different IDE, please refer to the documentation for your specific IDE to set up the linters and formatters.
You can also run the linters manually using the npm run lint command in the root directory of the project. This will run the linters for both the frontend and backend applications and report any errors or warnings.
You can also run the formatters manually using the npm run format command in the root directory of the project. This will format the code for both the frontend and backend applications using Prettier.
This will automatically apply consistent formatting to the code based on the configuration specified in the .prettierrc.json file.
If you want to run the formatters separately, you can use the npm run frontend:format or npm run backend:format commands to format the code for the frontend or backend applications, respectively.
TBD, will use docker-compose and a reverse proxy (nginx) to serve the frontend and backend applications.
TBD
TBD
The frontend directory contains the frontend code for the application, built with React and TypeScript via Vite. It includes the user interface and client-side logic.
The important main files and directories in the frontend directory are:
src: The source code for the frontend application. It includes the main application code, components, styles, and other assets.components: Contains reusable React components used throughout the application.pages: Contains the main pages of the application, each representing a different route in the app.styles: Contains stylesheets and CSS files used in the application.App.tsx: This is the main entry point for the React application. It sets up the routing and renders the main components.index.tsx: This is the main entry point for the Vite application. It renders the React app into the DOM (what the browser renders).
public: This directory contains static assets that are served directly by the web server. It includes images, icons, and other files that do not require processing by the build tool.vite.config.ts: This file contains the configuration for Vite, the build tool used for the frontend application. It specifies how the application should be built and served, including settings for development and production environments.tsconfig.json: This file contains the TypeScript configuration for the frontend application. It specifies the compiler options, including the target version of JavaScript, module resolution, and other settings.eslint.config.js: This file contains the ESLint configuration for the frontend application. It specifies the rules and settings for linting the code, including which files to lint and which rules to apply..prettierrc.json: This file contains the Prettier configuration for the frontend application. It specifies the formatting rules for the code, including indentation, line length, and other settings.index.html: This is the main HTML file for the frontend application. It includes the root element where the React app will be rendered and any other static assets that need to be included in the HTML.
The backend directory contains the backend code for the application, built with Go. It includes the API and database logic.
The important main files and directories in the backend directory are:
cmd: This directory contains the main entry point for the backend application. It includes the main Go file that starts the server and handles incoming requests.internal: This directory contains the internal packages and logic for the backend application. It includes the API handlers, database models, and other core functionality.config: This directory contains the configuration files and settings for the backend application. It includes the database connection settings, API keys, and other environment-specific configurations.handlers: This directory contains the API handlers for the backend application. It includes the logic for handling incoming requests and returning responses.routes: This directory contains the routing logic for the backend application. It includes the definitions of the API endpoints and how they map to the handlers.
.golangci.yml: This file contains the configuration for GolangCI-Lint, a linter for Go code. It specifies the rules and settings for linting the code, including which files to lint and which rules to apply.go.mod: This file contains the Go module definition for the backend application. It specifies the module name, dependencies, and other settings for the Go project. (sort of like package.json, or any other package manager)go.sum: This file contains the Go module checksum for the backend application. It ensures that the same versions of dependencies are used when the project is built or installed on different machines or environments. Do not edit this file manually; it is managed by Go.
If you stumble upon this, this is mostly closed to the public for now and is not open for contributions; this was pioneered to help my friends learn more as they are starting out in their careers. However, if you have any suggestions or feedback, please feel free to reach out to me directly. I would love to hear your thoughts and ideas for improving the project.