Foundations & Project Setup

Create the repo

From an empty parent folder:

mkdir url-shortener && cd url-shortener
git init -b main
gh repo create url-shortener --public --source=. --remote=origin
# Or skip the gh command and create the repo via github.com later.

Initialize the Node project

npm init -y
npm pkg set type="module"
npm pkg set engines.node=">=20"

Install TypeScript and runtime dependencies

npm install express
npm install -D typescript tsx @types/node @types/express \
              eslint @eslint/js typescript-eslint prettier

Configure TypeScript

Create tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "outDir": "dist",
    "rootDir": "src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"]
}

Write the hello-world server

Create src/server.ts:

import express from 'express';

const app  = express();
const port = Number(process.env.PORT ?? 3000);

app.get('/health', (_req, res) => res.json({ ok: true }));
app.get('/',       (_req, res) => res.send('URL Shortener — hello!'));

app.listen(port, () => console.log(`listening on :${port}`));

Add npm scripts

npm pkg set scripts.dev="tsx watch src/server.ts"
npm pkg set scripts.build="tsc"
npm pkg set scripts.start="node dist/server.js"
npm pkg set scripts.lint="eslint src"
npm pkg set scripts.format="prettier --write ."

Run it:

npm run dev

Set up linting and formatting

Create eslint.config.js:

import js from '@eslint/js';
import tseslint from 'typescript-eslint';

export default [
  js.configs.recommended,
  ...tseslint.configs.recommended,
  { ignores: ['dist/**', 'node_modules/**'] }
];

Create .prettierrc.json:

{ "singleQuote": true, "semi": true, "printWidth": 100 }

Add an .editorconfig and .gitignore

.editorconfig:

root = true
[*]
indent_style = space
indent_size = 2
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true

.gitignore:

node_modules
dist
.env
.env.*
!.env.example
*.log
.DS_Store

Write the design doc

Create docs/design.md with this skeleton — keep it to one page.

# URL Shortener — Design

## Problem
Users want short, shareable URLs that redirect to long ones.

## Goals
- POST /shorten → returns a short code
- GET /:code → 302 redirects to the original URL
- Per-user ownership of links
- 99.95% redirect availability over 30 days

## Non-goals (v1)
- Custom domains
- Click analytics dashboard (will arrive in module 6)
- Mobile app

## Sketch
Client → Express → Redis (cache) → Postgres
                ↘ Queue → Worker → clicks table

## Open questions
- ID scheme: random base62 vs hash? (decide in module 2)
- Anonymous quota? (decide in module 5)

Commit, push, protect

git add .
git commit -m "module 01: scaffold typescript express server"
git push -u origin main

On GitHub: Settings → Branches → Add rule for main:

• Require a pull request before merging.
• Require status checks to pass (we'll add the actual checks in Module 08).
• Disallow direct pushes to main.