Creating an Internal Package

Create an empty directory

You'll need a directory to put the package in. Let's create one at ./packages/math.

Add a package.json

Next, create the package.json for the package. By adding this file, you'll fulfill the two requirements for an Internal Package, making it discoverable to Turborepo and the rest of your Workspace:

{
  "name": "@repo/math",
  "type": "module",
  "scripts": {
    "dev": "tsc --watch",
    "build": "tsc"
  },
  "exports": {
    "./add": {
      "types": "./src/add.ts",
      "default": "./dist/add.js"
    },
    "./subtract": {
      "types": "./src/subtract.ts",
      "default": "./dist/subtract.js"
    }
  },
  "devDependencies": {
    "@repo/typescript-config": "*",
    "typescript": "latest"
  }
}

Let's break down this package.json piece-by-piece:

• scripts: The dev and build script compile the package using the TypeScript compiler. The dev script will watch for changes to source code and automatically recompile the package.
• devDependencies: typescript and @repo/typescript-config are devDependencies so you can use those packages in the @repo/math package. In a real-world package, you will likely have more devDependencies and dependencies - but we can keep it simple for now.
• exports: Defines multiple entrypoints for the package so it can be used in other packages (import { add } from '@repo/math').

Notably, this package.json declares an Internal Package, @repo/typescript-config, as a dependency. Turborepo will recognize @repo/math as a dependent of @repo/typescript-config for ordering your tasks.

Add a tsconfig.json

Specify the TypeScript configuration for this package by adding a tsconfig.json file to the root of the package. TypeScript has an extends key, allowing you to use a base configuration throughout your repository and overwrite with different options as needed.

{
  "extends": "@repo/typescript-config/base.json",
  "compilerOptions": {
    "outDir": "dist",
    "rootDir": "src"
  },
  "include": ["src"],
  "exclude": ["node_modules", "dist"]
}

You've done four important things here:

• The @repo/typescript-config/base.json configuration that lives in ./packages/typescript-config has all the configuration you need so you extend from it.
• The outDir key in compilerOptions tells TypeScript where to put the compiled output. It matches the directory specified in your exports in package.json.
• The rootDir key in compilerOptions ensures that the output in outDir uses the same structure as the src directory.
• The include and exclude keys are not inherited from the base configuration, according to the TypeScript specification, so you've included them here.

Add a src directory with source code

You can now write some code for your package. Create two files inside a src directory:

export const add = (a: number, b: number) => a + b;

These files map to the outputs that will be created by tsc when you run turbo build in a moment.

Add the package to an application

You're ready to use your new package in an application. Let's add it to the web application.

  "dependencies": {
+   "@repo/math": "*",
    "next": "latest",
    "react": "latest",
    "react-dom": "latest"
  },

@repo/math is now available in the web application, you can use it in your code:

import { add } from '@repo/math/add';
 
function Page() {
  return <div>{add(1, 2)}</div>;
}
 
export default Page;

Edit turbo.json

Add the artifacts for the new @repo/math library to the outputs for the build task in turbo.json. This ensure that its build outputs will be cached by Turborepo, so they can be restored instantly when you start running builds.

{
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": [".next/**", "!.next/cache/**", "dist/**"]
    }
  }
}

Run turbo build

If you've installed turbo globally, run turbo build in your terminal at the root of your Workspace. You can also run the build script from package.json with your package manager, which will use turbo run build.

The @repo/math package built before the web application built so that the runtime code in ./packages/math/dist is available to the web application when it bundles.