Create a new project
January CLI helps you to scaffold a new project configured with all bits and pieces you need to start building your API.
npm create january@latest project-winter
Once done, you should see a new directory called project-winter
cd project-winter
Open it in your favorite code editor with two terminal windows.
The first terminal window will be used to run the build command and keep it running.
npm run build
The second terminal window will be used to run the server command and keep it running.
npm run dev
Prepare the development environment
By default, the project is configured to use PostgreSQL as the database, Hono as the framework, and Fly.io as the cloud provider.
To setup the database, you need to have a database server running locally which can be via either of the following methods:
Using pre-configured docker compose
The scaffolding process creates a tools/compose.ts
file that is pre-configured to prepare the development environment for you. Just run it and you shall be set.
- Open another terminal window and run the following command:
npx tsx tools/compose.ts
- Run postgres container, start the server, and watch for changes
docker compose \
-f "compose.dev.yml" \
up \
--build \
--watch \
--remove-orphans
This command uses docker --watch
mode to automatically restart the server when you make changes.
Using standalone postgres container
- Create postgres container
docker run \
--name postgres \
-e POSTGRES_PASSWORD=yourpassword \
-e POSTGRES_USER=youruser \
-e POSTGRES_DB=yourdatabase \
-d \
-p 5432:5432 \
postgres:16
- Update the
.env
file
CONNECTION_STRING=postgresql://youruser:yourpassword@localhost:5432/yourdatabase
- Run the server
npm run dev
This command uses Node.js version 18 --watch
mode to automatically restart the server when you make changes.
Structure of a project
Every project is a TypeScript project with the following structure:
.
├── package.json
├── tools
│ ├── extensions.js
│ └── compose.ts
├── src
│ ├── extensions
│ │ └── user
│ │ └── index.ts
│ └── project.ts
└── tsconfig.json
-
project.ts
file is the entry point and the only file (for now) that you use to build your project. -
src/extensions
is user-defined extensions that you can use to extend the functionality of the project. -
tools/extensions.js
file is used to configure the extensions. -
tools/compose.ts
is a TypeScript file that is used to generate a docker compose file for your project to ease the development on your local machine.