Understand the package artifact

You publish a prepared archive, not your working directory and not TypeScript source by itself.

Four objects that beginners often mix together

Source
The TypeScript, tests, configuration, and documentation that maintainers edit in a repository.
Build output
The JavaScript, declaration files, and source maps created by TypeScript or a bundler. This course uses tsc, not a bundler.
Package tarball
A compressed .tgz archive containing the files selected for users. pnpm pack creates this artifact.
Registry release
A package name and immutable version stored by npm. Consumers install that release into their own projects.

The delivery path

A failure at any arrow can produce a package that works in the repository but fails after installation. Production checks must exercise the whole path.

Package and SDK are related, not identical

An npm package is the distribution unit. An SDK is a library designed around a service or platform. An SDK package usually handles request construction, authentication, response validation, typed errors, and stable domain types.

A five-line utility can be a package. A quiz client that translates JavaScript options into HTTP requests is an SDK. npm distributes both in the same tarball format.

Users receive runtime code and type information

JavaScript

dist/index.js runs. It creates URLs, calls fetch, validates data, and throws errors.

Declarations

dist/index.d.ts tells TypeScript what users may pass and what each call returns. It does not run.

A type is not a runtime check

TypeScript removes types when it creates JavaScript. JSON from a server remains untrusted until runtime code validates it.

Design backward from the consumer

This is the experience the package must support:

pnpm add @your-scope/quiz-sdk
import { getQuestions } from "@your-scope/quiz-sdk";

const result = await getQuestions(
  { category: "science", count: 5 },
  { baseUrl: "https://quiz.example", fetch },
);

console.log(result.questions);

Every later decision exists to make this import predictable. The folder layout, compiler options, exports map, dependencies, tests, and release process all support this consumer call.

Official references

Check your understanding

  1. If src/index.ts changed but dist/index.js did not, which version can a consumer receive?

    Show answer

    The consumer can receive the old behavior from dist/index.js. Packaging does not guarantee that build output matches source. A later lesson adds prepack to rebuild before every tarball.

  2. Can index.d.ts reject malformed JSON at runtime?

    Show answer

    No. Declaration files help TypeScript check consumer source. Runtime JavaScript must validate external data.