Let's Build a Full Stack Application

This full stack app boilerplate consists of:

• an Express web server,
• a PostgreSQL database instance,
• and a React front-end

You'll also find a bunch of convenient commands and workflows that will allow you to develop your app locally and deploy it to heroku. Let's dive in!

Local Development

Getting Started

1. Fork and clone this repo to your local machine, then run the following commands to reinitialize your git history from scratch:

# these commands reset your git history
$ rm -rf .git
$ git init

2. Create a bare GitHub repo (no .gitignore, README.md, CHANGELOG.md, or license) and copy the ssh address to assign to your local clone with git remote add origin <paste-your-ssh-address-here>

3. npm install to add project dependencies to your local machine.

4. Choose a name for your local database instance and edit db/index.js to assign the name to DB_NAME. Next, run createdb <your-db-name-goes-here> from your command line to spin up your database.

5. npm run start:dev will build your React app and start your express server in concurrent mode (meaning that both processes run in the same terminal window). Once this command is running, you can start developing! nodemon and react-scripts will listen to file changes and update continuously (hot-module-reloading).

NB: If you see a proxy error message in the terminal, just hard refresh your browser window and you'll be all set.

Project Structure

├── .github/workflows
│   └── heroku-deploy.yaml
│  
├── api
│   ├── apiRouter.test.js
│   └── index.js
│
├── db
│   ├── models
│   │   ├── index.js
│   │   └── user.js
│   ├── client.js
│   ├── index.js
│   └── init_db.js
│
├── public
│   └── index.html
│
├── src
│   ├── axios-services
│   │   └── index.js
│   ├── components
│   │   ├── App.js
│   │   └── index.js
│   ├── style
│   │   ├── App.css
│   │   └── index.css
│   └── index.js
│
├── .gitignore
├── index.js
├── package-lock.json
├── package.json
└── README.md

/db contains your index.js which exports the client instance and your database adapter models, as well as init_db.js which should be run when you need to rebuild your tables and seed data.

/public and /src are the two puzzle pieces for your React front-end. /public contains any static files necessary for your front-end. This can include images, a favicon, and most importantly the index.html that is the root of your React application.

src/axios-services contains your axios network request adapters. src/components contains your React component files.

Inside /api you have index.js which is responsible for building the apiRouter that you'll attach in the express server, and apiRouter.test.js which will give you direction on test-driven development for your api. Your React application and Express server use any routes you build in the /api directory to send/receive data via JSON, for example, a usersRouter.js that will be required and mounted in the apiRouter.js.

Rounding things out, we've got the top level index.js that creates your Express Server. This should be responsible for setting up your API, starting your server, and connecting to your database. We've also got our .gitignore, package-lock.json, and package.json where you'll find the scripts necessary to get your app off the ground, as well as this README.md.

Command Line Tools

In addition to start:dev, client:build, client:dev and server:dev, you have access to db:build which rebuilds the database, all the tables, and ensures that there is meaningful data present.

Deployment

Setting up Heroku

Setup your heroku project by choosing a site name and provisioning a postgres database. These commands create a heroku project backed by a postgres db instance which will live at https://project-name-goes-here.herokuapp.com. You'll want to replace project-name-goes-here with your selected project name.

You'll only need to do this step once, at the outset of your project:

# create your project
$ heroku create project-name-goes-here
# create your database instance
$ heroku addons:create heroku-postgresql:hobby-dev

Next we'll configure your database instance to ignore the ssl configuration object our pg client instance expects:

# set ssl mode to no-verify
$ heroku config:set PGSSLMODE=no-verify
# confirm your environment variable has been set
$ heroku config

Configuring GitHub Actions Secrets for CI/CD

We're going to leverage continuous integration and continuous development methodologies, or CI/CD, to deploy your app. To enable CI/CD you'll need to add a few environment variables to your project repo.

Under Settings, choose the Secrets option under Security. You'll see the following dialog, and you'll be able to add a secret by selecting the New repository secret button. Once you create a GitHub secret you can never see it again, but you can modify it! We're going to add 3 secrets to our repo:

• HEROKU_API_KEY: you'll find this listed in your heroku account settings
• HEROKU_APP_NAME: this is the project name you chose above
• HEROKU_EMAIL: this is the email address associated with your heroku account

Each project group will elect one person to be the "owner" of the heroku account, and that person's api key and email address will be used to register the secrets above.

After the bootcamp ends, you might want to redeploy and make changes to your team's application. Once you've forked this repo to your personal GitHub Account, you can add your own secrets and redeploy under a different heroku app name!

Deployment

In .github/workflows you'll find a YAML, an acronym for "YAML Ain't Markup Language", that triggers an automated deployment by watching your main branch: whenever a new pull request is merged to main, your app will automagically deploy itself on heroku.

Optionally, you can also trigger this deployment workflow by pushing to the deploy branch. Many companies use this pattern to enable hotfixes without going through the lengthy review process of creating a PR and merging it.

Note that this workflow does not seed your database. To seed your remote postgres instance, run the following command:

# this command seeds your remote postgres instance
$ heroku run npm run db:build

As you project grows you'll probably want to re-seed and refresh your database from time to time. Rerun this command whenever you want to re-seed.

Wrapup

You'll be able to view your fullstack application by running heroku open. Bask in the glory of your live site, and happy coding!