typescript-monorepo-next-example

typescript-monorepo-next-example is a Boilerplate sample that shows how to structure a TypeScript 3 monorepo around a Next.js application and a shared React component package. It provides step-by-step commands to create the workspace from scratch, using Yarn workspaces for dependency management and separate packages for the app and reusable UI components.

What is typescript-monorepo-next-example?

This repository is a working example of a TypeScript monorepo that combines a Next.js app (packages/app) with a shared component library (packages/component-a). It takes no input; you clone or replicate the structure to get a runnable Next.js site that imports a component from a separately managed package. The project runs on Node with Yarn and is maintained by the GitHub account deptno, which also publishes related example repos.

Key Features

• Yarn workspaces monorepo — The root package.json defines workspace directories and scripts, so packages/app and packages/component-a share a single node_modules folder.
• Next.js app package — packages/app includes Next.js, React, ReactDOM, and @zeit/next-typescript, with pages/index.tsx as the default entry page.
• Shared TypeScript configuration — packages/tsconfig.json and packages/tsconfig.base.json centralize compiler options that all workspace packages inherit.
• Reusable component package — packages/component-a exports a React component in index.tsx that the Next.js app imports as a dependency, demonstrating cross-package code sharing.
• Build and watch scripts — The root scripts include yarn build:packages for one-off compilation and yarn build:packages:watch for rebuilding the component package on changes.
• TypeScript 3 requirement — The README explicitly states that TypeScript 3 or above is required, meaning older versions will not work.

Who is it for?

• Developers learning monorepo setups — They can follow the documented mkdir and yarn init commands to recreate the structure from an empty directory.
• Next.js users who want shared components — They can see exactly how to extract UI code into a separate package and then import it from the app, including the necessary package.json dependency entry.
• Teams standardizing on TypeScript — The shared tsconfig.base.json provides a concrete template for enforcing consistent compiler options across multiple packages.

What can you do with it?

• Bootstrap a new monorepo — Use the README's shell commands to create the root folder, package.json workspace, app, and component packages.
• Build a shareable component library — Package a component in packages/component-a, consume it from the Next.js app, and use yarn build:packages:watch to recompile during development.
• Compare with alternative setups — The Related section links to typescript-monorepo-cra-example (a Create React App version) and next.js-typescript-starter-kit (a non-monorepo Next.js starter) for side-by-side evaluation.

How does it work?

The setup starts by creating a root directory and running yarn init -y -p, then editing package.json to enable workspaces and define scripts. Next it creates packages/app with Next.js and TypeScript dependencies, configures next.config.js, .babelrc.js, and tsconfig.json, and adds a pages/index.tsx that imports from the component package. A separate packages/component-a folder holds the shared component and its own tsconfig.json. After running yarn, you compile the component with yarn build:packages and start the app with yarn start.

Alternatives

• typescript-monorepo-cra-example — the same monorepo pattern but built with Create React App instead of Next.js.
• next.js-typescript-starter-kit — a Next.js TypeScript starter that does not focus on a monorepo layout.

FAQ

Does this example work with older TypeScript versions?

No, the README states that TypeScript 3 or above is required, so earlier versions will not work.

How do I add a new package to the monorepo?

You would follow the pattern used for packages/component-a: create a new folder under packages/, run yarn init, add the necessary dependencies, and reference it from the app's package.json so Next.js can import it.

What commands do I run to start the app?

Run yarn to install dependencies, yarn build:packages (or yarn build:packages:watch) to compile the shared component, and yarn start to launch the Next.js development server.

Is this a production-ready boilerplate?

The repository is described as an example, so it is intended as a reference for structuring a TypeScript monorepo rather than a fully featured production template.