Project structure · More
TypeScript npm library project structure
Opens with creditsA small, typed npm package (a retry helper) built the way modern libraries ship in 2026: TypeScript source in src, bundled by tsdown into dist with type declarations and an exports map, tested with Vitest, checked with publint and Are the Types Wrong, versioned with Changesets and published from CI with npm provenance. For students who want to publish their first package, and for anyone whose package works locally but breaks for users.
Curated by Tauseef FayyazIntermediate123 files and foldersTypeScript 7.0 (tsgo), tsdown 0.23, Node 24 LTS (builds need 22.18 or newer)Checked October 2026How it grows
Each stage opens the explorer there
- 1Day 1What the scaffold and your first hour give you15 files and folders
- 2GrowingWhat a real app with features and tests adds+44 files and folders
- ProductionWhat running it for real users adds+26 files and foldersOpens with credits
- ExpertWhat a team needs to keep it healthy for years+38 files and foldersOpens with credits
How it is organised
- Users import `dist`, not `src`. Every check that matters (types, exports, Node versions) runs against the built package.
- The `exports` map is the public API boundary: entries listed there can be imported, nothing else can. Let tsdown generate it, then verify it with publint and attw.
- Ship ESM, and add CJS only if your users still need `require`. Dual builds are fine when tsdown builds both from one source; hand-maintained duplicates are not.
- Zero runtime dependencies is the goal. Every dependency you add is installed by every user, forever.
- Every user-facing change comes with a changeset, so versions follow semver and the changelog writes itself.
- Releases come only from CI, with npm trusted publishing and provenance, never from a laptop.
- A breaking change is anything that can fail a user's build or tests: a removed export, a narrower type, a new required option. It waits for a major version.
At the top of the project
Open one in the explorer for the full story
- retry-kit/
- .git/Git history, created by `git init`.
- .changeset/Changesets config and pending change notes, one Markdown file per change.3 inside
- .vscode/Shared editor settings: Biome as formatter, the workspace TypeScript version.2 inside
- coverage/Coverage reports written by `vitest --coverage`.
- dist/Build output: `index.mjs`, `index.d.mts`, source maps, and per-entry files. This is what npm publishes.
- examples/Small runnable examples that import the package by name.3 inside
- node_modules/Installed dev dependencies.
- src/The library source: everything users can import, plus internal helpers they cannot.9 inside
- tests/Vitest tests for the source, type tests, and consumer tests for the built package.9 inside
- .editorconfigIndentation and line ending rules every editor understands.
- .gitignoreIgnores node_modules, dist, logs and .DS_Store.
- .node-versionPins the Node version for development and building, for example 24.
- lefthook.ymlGit hooks: Biome check on staged files before each commit.
- pnpm-workspace.yamlpnpm settings for the repo, such as which dependencies may run install scripts.
- biome.jsonBiome config: one fast tool for linting and formatting TypeScript, JSON and CSS.
- CHANGELOG.mdRelease notes for every version, written by Changesets from the pending changesets.
- CONTRIBUTING.mdHow to set up, test, add a changeset and open a pull request.
- LICENSEThe license text, matching the `license` field in package.json.
- package.jsonName, version, the `exports` map, `files`, `engines`, scripts and dev dependencies.
- pnpm-lock.yamlExact versions of every dev dependency, for reproducible builds.
- README.mdWhat the package does, install, one example, links to docs. Shown on npm and GitHub.
- tsconfig.jsonStrict TypeScript settings with `isolatedModules` and `verbatimModuleSyntax`, used for type checking and declarations.
- tsdown.config.tstsdown build config: entries, formats, declarations, auto exports, and packaging checks.
- vitest.config.tsVitest settings: test folders, type checking of `.test-d.ts`, coverage.
Learn more on Sefism
Roadmaps, cheat sheets and projects that go with TypeScript npm library.
- RoadmapOpen source roadmapFirst contribution to programmes
- Roadmap· TypeScriptSoftware design and clean code roadmapOOP, SOLID, design patterns, refactoring
- Roadmap· Node.jsBackend development roadmapAPIs, databases, auth, deploys
- RoadmapLinux, terminal and Git roadmapShell, Git, SSH and your dev setup
- Cheat sheetOpen source cheat sheetFirst contribution to programmes.
- Cheat sheetSoftware design and clean code cheat sheetOOP, SOLID, design patterns, refactoring.
- Cheat sheetLinux, terminal and Git cheat sheetShell, Git, SSH and your dev setup.
- FYP idea· AdvancedDependency Upgrade Impact Checker That Finds Which of Your Calls a Breaking Change HitsBuild a tool for TypeScript projects that compares the public API of two versions of an npm package, finds the breaking changes, then searches your own code for the exact call sites they affect. Dependabot and Renovate open upgrade pull requests but cannot say whether a major version bump touches anything you use. This tool answers that question with a list of files and lines, so small teams stop putting off upgrades.
- FYP idea· AdvancedVulnerable Function Reachability Checker for JavaScript and TypeScript DependenciesBuild a tool that tells a JavaScript or TypeScript team whether their code actually calls the vulnerable function behind each dependency alert, not just whether the package version is affected. Go has this built in with govulncheck; the npm world mostly does not have a free equivalent. The result is fewer, more trustworthy alerts, with a call path as evidence for each one that matters.
See 9 moreShow fewer
- FYP idea· BeginnerHallucinated Package Guard for AI Coding Assistants (Slopsquatting Defence)AI coding assistants sometimes suggest packages that do not exist. Attackers can register those names and wait. Build a guard that checks every new dependency added to a project, by a person or an AI, against the real registry: does it exist, how old is it, who maintains it, does it look like a typo of a popular package, and was it suggested by an AI? It runs in the editor, as a pre-commit hook and in CI.
- FYP idea· IntermediateSigned Build Provenance Gate for a Company's Internal Packages and Container ImagesBuild a gate that lets a small company prove every internal package and container image was built by its own CI from a reviewed commit, and blocks anything that was not. It uses keyless signing from the Sigstore project and SLSA-style provenance, wrapped into a setup a team can adopt in an afternoon. Deployments and installs check the signature and the build record before they proceed.
- QuestionShould I learn TypeScript or Python first in 2026?Learn Python first if you are new to programming or drawn to data and AI. Learn TypeScript first only if you already know some JavaScript or are certain about web development, and even then learn plain JavaScript for a few weeks before the types. The second language is much easier than the first.
- QuestionWhat does proof of work mean for a fresher developer?Proof of work is evidence someone can check in a few minutes that you can do the job: a deployed project real people could use, readable code with tests, a pull request merged into someone else's project, or a clear write-up of a problem you solved. It replaces the experience a fresher does not have yet, so it must be easy to find and easy to verify.
- QuestionHow do I learn to write clean code as a junior developer?Clean code is a set of habits, not a book you finish. Fix names, function size, flag arguments and error handling one habit at a time, let a formatter and linter settle style, learn to refactor in small steps behind tests, and keep a list of the review comments you get twice: that list is your personal curriculum.
- Resource· GuideThe TypeScript HandbookThe TypeScript Handbook is the official, free guide to TypeScript's type system from the TypeScript team, written for working programmers and kept current with each release. It covers everyday types, narrowing, functions, object types, generics, type manipulation, classes and modules, and it is designed to be read in a few hours. It suits JavaScript developers adopting TypeScript and anyone who writes types by copying patterns without understanding them.
- Resource· GuideVitest DocumentationThe official documentation for Vitest, the test runner built on Vite. Its getting started guide has you writing and running a real test in minutes, then covers matchers, async tests, setup and teardown, mocking (functions, modules, timers, dates, requests), snapshots, coverage, the UI dashboard and browser mode for component tests. It uses a Jest-compatible API, so it suits JavaScript and TypeScript developers starting to test, and teams moving from Jest.
- Resource· GuideNode.js LearnThe official Node.js Learn guides explain what Node itself is doing underneath your framework: the event loop, asynchronous work, files and streams, HTTP, environment variables, running TypeScript, diagnostics and the built-in test runner. The articles are short and free. They suit JavaScript developers who use Express, Next.js or another tool but want to understand the runtime, and anyone debugging a problem that a framework tutorial glosses over.
- Resource· GuideGitHub Actions DocumentationThe official documentation for GitHub Actions, GitHub's built in CI/CD and automation system: workflow syntax, triggers, runners, caching, artifacts, environments, secrets and OpenID Connect deployments to AWS, Azure and Google Cloud. Actions is free for public repositories on standard runners, so it is the CI tool most students and open source projects learn first. It suits developers setting up tests and deployments for the first time.
Checked against 18 official sources, October 2026. If something has changed, the docs win.Show sourcesHide sources
- tsdown: Getting started
- create-tsdown default template
- tsdown: Package exports
- tsdown: Package validation (publint and attw)
- tsdown: Migrate from tsup
- Node.js: Packages (exports and conditions)
- publint rules
- Are the Types Wrong?
- Changesets
- changesets/action
- npm: Trusted publishing
- npm: Generating provenance statements
- npm: Deprecating a package version
- Vitest: Testing types
- Biome: Configuration
- API Extractor
- size-limit
- GitHub: Adding a security policy
Best practices and checklists for this stack
Picked from the other libraries by shared topics.
Best practices
See all- Code Review Best PracticesCode review best practices for reviewers and authors: the approval standard, what to look for, review speed, writing kind and useful comments, handling disagreement and small changes.
- Software Testing Best PracticesTesting best practices for unit, integration and end-to-end tests: test design, test doubles, flaky tests, coverage and fast CI, with examples in TypeScript and Python.
- Python Best PracticesWrite Python that stays maintainable: supported versions, pyproject and lockfiles, Ruff, type hints, errors, logging, concurrency, pytest and security.
Checklists
See all- Pull Request Checklist: Before You Open a PRA pull request checklist to run before you ask for review: scope and size, a clean diff, tests, a clear description, safe releases and a tidy branch, each with a way to verify it.
- Career Switch into Tech ChecklistMove into software from another field step by step: choose a direction, follow a learning plan, build proof of skill, use your previous domain, network, plan your runway and target a first role.
Work with me
Stuck on something specific?
Writing only gets you so far. If you want an answer to your situation rather than the general case, book a session and we will work through it together. Sessions are free for approved Sefism members, and a few slots open each week.
- 1:1 Mentorship
- Fresh Graduate Mentorship
- Career Guidance
Brand deals, promos and partnerships: tauseeffayyaz@gmail.com