Build and ship projects

Turning skills into finished, shareable work: scoping, JSON and APIs, dependencies, configuration, a good README and publishing on GitHub.

Scoping a small project

Also called MVP, minimum viable product, milestones

What: Cutting an idea down to the smallest version that solves one real problem end to end, then splitting it into a handful of milestones.
Why: Finished small projects teach more and show more than ambitious unfinished ones.
Example: Not "a personal finance app", but "a command-line tool that reads my bank CSV and prints spending per category per month". Milestones: parse the CSV, categorise, total, print, test, README.

Watch out

Starting with login, a database and a UI before the core logic works at all.

Reading and writing JSON

Also called JSON, serialisation, parsing JSON, JSON.parse

What: JSON is a text format for objects, arrays, strings, numbers, booleans and null. Serialising turns your data into JSON; parsing turns JSON back into data.
Why: It is how most APIs and many config and save files exchange data. Python, JavaScript and C# ship a JSON library; Java and C++ usually add Jackson or nlohmann/json.

JavaScript

import { readFile, writeFile } from 'node:fs/promises';

const data = JSON.parse(await readFile('ledger.json', 'utf8'));
data.entries.push({ amount: 12.5, note: 'lunch' });
await writeFile('ledger.json', JSON.stringify(data, null, 2));

Watch out

Trusting parsed JSON blindly: fields can be missing, null or the wrong type, so validate before use.

Calling a public API

Also called HTTP, REST API, fetch, HttpClient, requests

What: Sending an HTTP request (usually GET or POST) to a web service and reading its response, typically a status code plus a JSON body.
Why: Public APIs give a small project real data (weather, books, transport) without building a backend.

JavaScript

const url = 'https://jsonplaceholder.typicode.com/todos/1';
const signal = AbortSignal.timeout(10_000);
const res = await fetch(url, { signal });
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const todo = await res.json();
console.log(todo.title);

Watch out

Assuming the call succeeds: set a timeout, check the status code and handle the network being down.

npm and package.json

Also called npm, npm install, package-lock.json, node_modules, devDependencies

What: package.json lists a project's dependencies and scripts. npm install downloads packages into node_modules, and package-lock.json pins the exact versions.
Why: It makes installs reproducible and gives everyone the same commands, such as npm test. Development-only tools go in devDependencies.

Shell

npm init -y
npm install zod
npm install --save-dev vitest
npm ci
npm test

Watch out

Committing node_modules, or not committing package-lock.json, so installs differ between machines.

Configuration and secrets

Also called environment variables, .env, API keys

What: Settings that change between machines (API keys, URLs, file paths) are read from environment variables or a local config file instead of being written into the code.
Why: It keeps secrets out of Git and lets the same code run on your laptop, a friend's machine and a server.

JavaScript

const apiKey = process.env.WEATHER_API_KEY;
if (!apiKey) {
  throw new Error('WEATHER_API_KEY is not set');
}

Watch out

Committing an API key: bots scan GitHub within minutes, so revoke the key at once, since deleting the commit is not enough.

Writing a README

Also called README.md, project documentation

What: The front page of a repository: what the project does and for whom, a demo, how to install, run and test it, how it works and its known limits.
Why: It is the first thing a reviewer, teammate or employer reads, and often the only thing. A project nobody can run might as well not exist.

MARKDOWN

# Ledger
One sentence: what it does and who it is for.

## Demo
A GIF or two screenshots.

## Getting started
Requirements, then install and run commands.

## Running tests
## How it works
## Limitations and next steps

Watch out

Leaving the default template, or skipping the exact commands to run the project from a fresh clone.

Publishing on GitHub

Also called gh repo create, licence, portfolio

What: Pushing a project to a public GitHub repository with a README, a licence, a .gitignore and a clean history of meaningful commits.
Why: It backs your work up, makes it easy to share, and shows how you work, not just what you built.

Shell

git remote add origin https://github.com/you/ledger.git
git branch -M main
git push -u origin main

gh repo create ledger --public --source=. --push

Watch out

Pushing one "initial commit" containing the entire finished project, which hides how it was built.

Go deeper