full-stack-project

A full stack TypeScript solo project.

Getting Started

---

Use this template to create a new repo on your GitHub account

1. Click the green Use this template button, select Create a new repository
   1. Under Owner select your username
   2. Give your repository a name. Name it after your application. The name full-stack-project is not a good name.
   3. (Optional) Add a description
   4. Leave repository as Public
   5. DO NOT Include all branches
   6. Click the green Create repository from template button

---

Clone Newly created repo into lfz-code

1. From your newly created repo on GitHub, click the green <> Code button, then copy SSH URL
2. Open lfz-code, click on blue >< button in bottom left of lfz-code
   1. Select Clone Repository in Container Volume...
      • If this option does not appear, open the Command Palette (cmd-shift-P on Mac or ctrl-shift-P on Windows), type "Dev Containers", and select Clone Repository in Container Volume.... Then continue to the next step.
   2. Paste SSH URL for your repo, click Clone git repository from URL

---

Run and test project setup

Getting Started

1. Install all dependencies with npm install.

Create the database

If your project will be using a database, create it now.

1. Start PostgreSQL

   sudo service postgresql start

2. Create database (replace name-of-database with a name of your choosing, such as the name of your app)

   createdb name-of-database

3. In the server/.env file, in the DATABASE_URL value, replace changeMe with the name of your database, from the last step
4. While you are editing server/.env, also change the value of TOKEN_SECRET to a custom value, without spaces.
5. Make the same changes to server/.env.example. (Don't worry about the TOKEN_SECRET, this value is used only during development. When you deploy, you will provide a different value using the AWS Secrets Manager.)

If your project will not be using a database, edit package.json to remove the dev:db script.

Start the development servers

1. Start all the development servers with the "dev" script:

   npm run dev

2. Later, when you wish to stop the development servers, type Ctrl-C in the terminal where the servers are running.

Verify the client

1. A React app has already been created for you.
2. Take a minute to look over the code in client/src/App.tsx to get an idea of what it is doing.
3. Go to the app in your browser. You should see the message from the server below the React logo, and in the browser console.
4. If you see the message from the server in your browser you are good to go, your client and server are communicating.

Set up the database

1. In your browser navigate to the site you used for your database design.

2. Export your database as PostgreSQL, this should generate the SQL code for creating your database tables.

   • Reach out to an instructor if you have any issues with this step

3. Copy the generated SQL code and paste it into database/schema.sql below the preexisting sql code in the file. The end result should look something like: (You will likely have more tables)

   set client_min_messages to warning;
   
   -- DANGER: this is NOT how to do it in the real world.
   -- `drop schema` INSTANTLY ERASES EVERYTHING.
   drop schema "public" cascade;
   
   create schema "public";
   
   create table "todos" (
       "todoId"      serial PRIMARY KEY,
       "task"        text not null,
       "isCompleted" boolean not null,
       "createdAt"   timestamptz not null DEFAULT now(),
       "updatedAt"   timestamptz not null DEFAULT now()
   );

4. In a separate terminal, run npm run db:import to create your tables

5. Use pgweb or psql to verify your tables were created successfully (see LFZ Database Guide for tips). Your database and tables should be listed; if not, stop here and reach out to an instructor for help

6. At this point your database is setup and you are good to start using it. However there is no data in your database, which isn't necessarily a bad thing, but if you want some starting data in your database you need to add insert statements into the database/data.sql file. You can add whatever starting data you need/want. Here is an example:

   insert into "todos" ("task", "isCompleted")
   values
       ('Learn to code', false),
       ('Build projects', false),
       ('Get a job', false);

7. After any changes to database/schema.sql or database/data.sql re-run the npm run db:import command to update your database. Use pgweb or psql to verify your changes were successfully applied.

Deployment

Once your template is set up and functional, deploy it. This will get all the deployment issues ironed out early. During development, you should re-deploy frequently to make sure that your code works properly in your production environment. Deployment instructions can be found HERE

---

Available npm commands explained

Below is an explanation of all included npm commands in the root package.json. Several are only used for deployment purposes and should not be necessary for development.

1. start
   • The start script starts the Node server in production mode, without any file watchers.
2. build
   • The build script executes npm run build in the context of the client folder. This builds your React app for production. This is used during deployment, and not commonly needed during development.
3. db:import
   • The db:import script executes database/import.sh, which executes the database/schema.sql and database/data.sql files to build and populate your database.
4. dev
   • Starts all the development servers.
5. lint
   • Runs ESLint against all the client and server code.
6. psql
   • When used on the EC2 instance, runs psql attached to the project database. Helpful for debugging issues with the database.
7. tsc
   • Runs the TypeScript compiler against all the client and server code.
8. Not directly used by developer
   1. install:*
   • These scripts install dependencies in the client and server folders, and copy .env.example to .env if it doesn't already exist.
   1. dev:*
   • These scripts start the individual development servers.
   1. lint:*
   • These scripts run lint in the client and server directories.
   1. tsc:*
   • These scripts run tsc in the client and server directories.
   1. postinstall
      • The postinstall script is automatically run when you run npm install. It is executed after the dependencies are installed. Specifically for this project the postinstall script is used to install the client and server dependencies.
   2. prepare
      • The prepare script is similar to postinstall — it is executed before install. Specifically for this project it is used to install husky.
   3. deploy
      • The deploy script is used to deploy the project by pushing the main branch to the pub branch, which triggers the GitHub Action that deploys the project.