Quick start

Get stuck in!

There are several ways that you can use this repo. Pick your poison.

Github

Git Clone

Standard procedure. Clone the repo and evolve it into whatever you need. Click for further instruction.

Github

Git Template

Pre-configured project structures that can be easily cloned and customized. Not much different from cloning.

NPM

NPM install

A full Express app as a module. Drop Residents into an existing Express app to add user and auth routes.

NPM [WIP]

NPX CLI tool

Coming soon - we'll have some `create residents app` commands so you can customise your setup.

Git Clone

If the steps below look like too much effort, the TL;DR is: Have Node and Postgres installed -> clone the repo -> npm install the dependencies -> set the db .env variables -> init the db -> run the app.

1

Clone the Repository

git clone git@github.com:conorluddy/Residents.git
2

Jump into the working directory

cd residents
3

Install the dependencies

npm install
4

Copy the example env file

cp .env.example .env

You'll need to go through and fill that out with your own configuration, but to get this running you just need the Postgres connection details for now.

5

Set up prerequisites

Residents is a database backed Express application, so it depends on Node and a Postgres database. It will run well on any Node version from 18 onwards. If you don't like Postgres it should be pretty easy to swap that out with your preferred SQL flavour too. We use Drizzle ORM here, which supports a bunch of databases.

If you don't have Node installed you can download it from here. Bun is probably an option too - haven't tried it though.

6

Set up Postgres

If you don't have Postgres, you can also get it here. You'll need to get that running locally and then set up your .env with the correct details.

7

Docker (alternative) option

Alternatively you can run everything on Docker if you prefer a containerized approach. You can download that here if you need to, and then kick it off with:

docker-compose up -d

Spinning up the Residents Docker environment will run both a database and the Residents app in containers. When you want to start coding, you can kill the app container and keep the Postgres container running, and point your local development environment at it with your .env variables.

8

Prepare the database tables

npm run push
9

Insert the first user [Optional]

There are some SEEDED_OWNER values in the .env - running this will insert that user into the database and will only work if there are no users in there already.

npm run seed:owner
10

Run the dev environment

npm run dev
11

Play around and start extending

If you use Postman, there's a Postman collection in the ./postman directory - you can import that whole into Postman and it will give you a collection of requests that you can use to test out the API. There should also be Swagger docs available at /api-docs

Git Template

Pre-configured project structures that can be easily cloned and customized. Not much different from cloning. Once you copy the template to your own repository just follow the same instructions as the git clone, but from your repo.

NPM install

Note: This is incomplete at the moment, I need to fix some dependency issues and make it play a bit nicer. Coming soon...

A full Express app as a module. Drop Residents into an existing Express app to add user and auth routes.

npm install residents --save

Because of Express modular nature, you can actually just use Residents like this and it will add our /auth and /user routes to an existing Express application.

import express from 'express'
import residents from 'residents'

const app = express()

app.use(residents) // Use Residents like any other middleware

app.use('/yourstuff', yourStuffRouter)

const server = app.listen(3000, () => {
  console.info('Server is Running.')
})

You'll need to have the same .env variables hooked up for Residents to be able to communicate with the database, and will need to prep the DB with the same commands as we use if you're working directly in the repo, e.g.

npm run push

We also expose some other useful bits from Residents to make it useful for quickly spinning up apps. Things you can import and use include:

  • Postgres DB client instance
  • Drizzle DB client instance
  • Authentication middleware
  • Types
  • Config
  • UI strings

These exports mean you can just piggyback on the functionality of Residents and apply the auth middleware to any of your own routes, quickly build Drizzle queries using the existing DB client, etc etc.

NPX CLI tool

Coming soon - we'll have some create residents app commands so you can customise your setup.