full-stack-skeleton

◦ Spin up a bleeding edge web-app in minutes

◦ Developed with the software and tools listed below:

---

📒 Table of Contents

• 📍 Overview
• 🚀 Getting Started
• 🎮 Workflow
• 🤝 Contributing
• 📄 License

---

📍 Overview

The project is a full-stack application that combines a frontend built with React + NextJS and a backend built with Go. The frontend utilizes the Next's App Router, with Tanstack Query handling data fetching and ShadcnUI as the UI component library. The backend uses Gin to serve a GraphQL API, which fetches data from a PostgreSQL database. The project is fully containerized with Docker and uses GitHub Actions for CI/CD.

---

🚀 Getting Started

✔️ Prerequisites

Before you begin, ensure that you have the following prerequisites installed:

• 🐳 Docker
• 🐿️ Go
• 🟩 Node.JS

📦 Installation

1. Clone the email-app repository:

git clone https://github.com/gwkline/full-stack-skeleton

2. Change to the project directory:

cd email-app

3. Start the development containers:

docker compose watch

To stop all containers:

docker compose down

---

✍️ Workflow

By default, the frontend is exposed on port 3000, and the backend is exposed on port 8888. All configuration happens in the root .env file. Rename the .env.example and fill with your own secret variables.

Example new feature workflow:

1. Pull the latest changes from the main branch:

#---------- git cli --------------
git checkout main
git pull origin main
#---------- oh-my-zsh --------------
gco main
ggpull 

2. Create a new branch with a descriptive name:

#---------- git cli --------------
git checkout -b "new-feature-branch"
#---------- oh-my-zsh --------------
gco -b "bugfix-issue-123"

3. Run this command in your terminal to start the development environment:

docker compose watch 

Backend

1. Create/update a service or resource in ./backend/pkg, including any business logic
2. To expose this logic, navigate to ./backend/graph and edit or create GraphQL types inschema/*.gql
3. Run the following command in the root directory to regenerate any dependent models, types, or resolvers:

(cd backend && go run github.com/99designs/gqlgen generate)

4. Back in ./backend/graph, update the corresponding resolvers/*_resolver.go file(s) to expose the finished service/resource
5. Write unit test(s) to verify your logic and attempt to prevent future bugs

Frontend

1. Navigate to ./frontend/lib, where you can create/update any needed GraphQL request functions.
2. We use a codegen to ensure all of the types match up with our GraphQL schema. Run the following command to generate the types:

(cd ./frontend && bun codegen)

3. Make sure the request you've written is properly typed, and then you can navigate to ./frontend/components and/or ./frontend/app to implement this feature
4. Create/update the necessary *.tsx or *.ts files to show off this new GraphQL mutation, query, or field
5. Dogfood on http://localhost:3000

Finishing Touches

1. Run this command in your terminal to stop the development environment:

docker compose down

2. Push your code and make a PR (see 🤝 Contributing)
3. Review your PR, make sure it passes CI/CD, then request your peers for review
4. Once approved and merged, let the CI/CD pipeline handle the rest - welcome to production!
5. Keep an eye on Sentry for any bugs

---

🧪 Running Tests

Right now testing is supported through unit tests on the Go backend:

(cd ./backend &&  go test -cover ./...)

To generate function mocks, we use mockery:

(cd backend && mockery)

---

🤝 Contributing

Contributions are always welcome! Please follow these steps:

1. Clone the project repository to your local machine using a Git client like Git or GitHub Desktop.
2. Create a new branch with a descriptive name (e.g., new-feature-branch or bugfix-issue-123).

#---------- git cli --------------
git checkout -b new-feature-branch

#---------- oh-my-zsh --------------\
gco -b new-feature-branch

4. Make changes to the project's codebase.
5. Commit your changes to your local branch with a clear commit message that explains the changes you've made.

#---------- git cli --------------
git add .
git commit -m "Implemented new feature."

#---------- oh-my-zsh --------------\
gcam "Implemented new feature."

6. Push your changes to the repository on GitHub using the following command

#---------- git cli --------------
git push origin new-feature-branch

#---------- oh-my-zsh --------------\
ggpush

7. Create a PR by navigating to Github - if you have Github CLI, you can use this command in your terminal:

gh pr create

In the pull request, describe the changes you've made and why they're necessary. The project maintainers will review your changes and provide feedback or merge them into the main branch.

---

📄 License

This project is licensed under the open-source MIT license

---