This project template is designed for junior developers aimed at gaining hands-on experience in full-stack development. This project includes a Node.js server with Express and a React client (powered by Vite), providing an opportunity to engage in frontend development, backend development, and API integration. Specifically the template is a full-stack MERN application for managing a library of rubber ducks - but you can modify it and build a library application of your choice.

This template includes a simple feature to display a random rubber duck from example READ ONLY database. This feature demonstrates the integration of the frontend with the backend and can be used to test if your setup is working correctly.

1. Client:
   • The home page contains a button labeled Show Random Duck.
   • When clicked, this button sends a request to the backend to fetch a random rubber duck.
   • The details of the random rubber duck, including its name and image, are displayed on the page.
2. Backend:
   • The server has an endpoint /api/rubberDucks/random that selects a random rubber duck from the database and returns its details in the response.
   • The server contains more endpoints, but without corresponding implementation in the client. These endpoints are to set example of more types of requests.

• Node.js
  • Version 20.x or higher required (latest LTS recommended)
• npm (will be typically installed automatically when you install Node.js above)
  • Version 10.x or higher required (get the latest by running npm install -g npm@latest --no-optional)

To get started with this project, you need to clone the repository to your local machine. Follow these steps:

1. Create a project from this repository by clicking on Use this template -> Create a new repository (more info here) - only ONCE per project
2. Clone the new Repository: https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository

1. Navigate to the server directory: cd server
2. Install server dependencies: npm install

1. Navigate to the client directory: cd ../client
2. Install client dependencies: npm install

Environment variables are used to configure your application without hardcoding sensitive information into your code. For this project, you need to set up the following environment variables in .env files located both in the server directory and client directory.

Make a copy of the .env.example file under the server folder and name it .env. This file contains the following environment variables (you don't need to touch them at this point):

• CLIENT_URL - this should match the URL of the client, which is what you'll see at the address bar of your browser after running your client (via npm start).
• PORT - This variable defines the port on which your Express server will run. By default, this is set to 5000, but you can change it to any available port number.

Make a copy of the .env.example file under the client folder and name it .env. This file contains the following environment variable (you don't need to touch them at this point):

• VITE_SERVER_API_URL: This variable contains the URL of your backend API. It tells your client where to send requests to interact with the server. By default, this should be set to http://localhost:5000/, but you should change it to match your server's actual URL if different (where 5000 is the PORT you defined in the server .env file above).

This section explains how to use the application once it’s set up and configured. Follow these steps to interact with both the client and server components of the application.

1. Open a terminal in the root folder of the cloned repository, and navigate to the server directory: cd server
2. Start the Express server in development mode: npm run dev
   • By default, the server will run on http://localhost:5000 (see configuration section above)

1. Open a new terminal in the root folder of the cloned repository, and navigate to the client directory: cd client

2. Run the Frontend Client: npm run dev

   • A new browser window with the client application should open (if you close the tab, you can return to it by navigating to http://localhost:3000/ by default)

• Click the Show Random Duck button to retrieve a random duck from the database and display its details on the screen.
• This feature helps verify that your frontend can communicate with the backend. If you see the random duck's details displayed on the page, your setup is working properly.
• You may also use an API client (like Postman) to directly test your API endpoints.

Please report any issues or provide feedback for further improvements!

• Stop the Express Server: In the terminal where the server is running, press Ctrl + C to stop the server.
• Stop the React Client: In the terminal where the client is running, press Ctrl + C to stop the client.

Ensure backend and frontend configurations (.env files) are correct.

• Server Issues:

  • Ensure that the React development server is running and that you have no conflicting applications using port 3000.
  • Check the terminal for error messages

• Client Issues:

  • Check the browser dev tools console for errors if the client is not displaying correctly (recommended: https://reactjs.org/link/react-devtools).
  • Check the browser dev tools network logs for failed requests

Contains the React (Vite) frontend application.

• package.json: Lists the client-side dependencies and scripts for managing the React application.
• .env: Stores environment variables like the API endpoint URL.
• index.html: Main HTML page hosting all the React components of the application (frontend entry point)
• public/: static assets that do not need to be processed by Vite's build pipeline. These files are copied as-is to the build output directory. In our case, the HTML's favicon.
• src/: Contains the source code for the React application.
  • assets/: assets that are part of the source code and need to be processed by Vite's build pipeline. This includes images, fonts, and other files that might be imported into your JS or CSS files. In our case, the QueenB summer camp logo.
  • components/: Reusable UI components such as buttons, forms, and other elements.
  • context/: Contains the React context for the ducks, responsible for pulling the current duck from the API
  • pages/: Page components that represent different routes in the application.
  • services/: Services for making API calls and handling business logic.
  • styles/: CSS and styling files for the application.
  • App.jsx: The main React component that sets up routing and renders the application.
  • index.jsx: The entry point for the React application, responsible for rendering the App component into the DOM.

Contains the Node.js / Express backend application.

• package.json: Lists the server-side dependencies and scripts for managing the Node.js application.
• .env: Stores environment variables like database connection strings and server port.
• server.js: The main server file that sets up Express, connects to the database, and starts the server (backend entry point).
• controllers/: Contains the logic for handling API requests and responses.
• data/: Contains the initial duck data (readonly database)
• images/: Contains the duck images referenced by the duck data above
• routes/: Defines the API endpoints and maps them to controller functions.

• Protect your main branch against direct pushes so only PRs are allowed.
  • A sample PR validation workflow is provided at .github/workflows/pr-validation.yml - note that it contains 7 jobs which can be added as checks.
  • Recommended - block merge commits and only allow squash (rebase) PR merges.
  • Docs: https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches
• Upon each merge to main, a package will be built by .github/workflows/official-build.yml
  • The same package is also created by the PR validation workflow, to validate that packaging hasn't been broken and to allow test env deployment (see below)

The repo includes a sample deployment workflow to Azure App Services Web App (which includes a free tier): https://azure.microsoft.com/en-us/products/app-service/web

• When deployed to a web app, the express server statically exposes the vite-compiled client.
  • To emulate this setup locally for debugging, run localBuild.ps1 followed by package.ps1 to create a package folder similar to the one generated in the workflows.
  • Then simply run npm run start in the package folder to have both API and client served on http://localhost:5000/ (you should be able to navigate to that address directly).
• The model in this repo assumes 3 GitHub environments: https://docs.github.com/en/actions/how-tos/deploy/configure-and-manage-deployments/manage-environments
  • Test - used to deploy PR build artifacts (manually dispatched via .github/workflows/deploy-test.yml)
  • Stage - used for continuous deployment (automatically dispatched upon official build completion via .github/workflows/deploy-stage.yml)
  • Prod - used for production deployment of official build artifacts (manually dispatched via .github/workflows/deploy-prod.yml)
• Note that each of the above environments requires its own web app (so you'd have 3 in total)
  • Under each GitHub environment, specify the corresponding web app's name in the AZURE_WEBAPP_NAME environment variable
• In order for deployment to work, you will need to follow the docs (specifically, create the repo secrets mentioned there for OIDC login): https://learn.microsoft.com/en-us/azure/app-service/deploy-github-actions?tabs=openid%2Caspnetcore
• In order for the deployment job to be able to fetch the built package from the build workflow, you'll need to create a GH_PAT_ACTIONS_READONLY repo secret containing a GitHub Personal Access Token (PAT) with actions:read permissions on your repo: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens

Full guide

For any issues please contact us via mail or open an issue.

Happy Coding! :)