Conventions

Projects that use ts should adhere to / assume the following conventions:

Source Files & Build Artifacts

Source files should be contained in the directory indicated in compilerOptions.baseUrl in tsconfig.json. Build artifacts will be written to compilerOptions.outDir in tsconfig.json.

tsconfig.json determines where source files should be located and where build artifacts will be written to:

tsconfig.json

{
  "compilerOptions": {
    "baseUrl": "src",
    "outDir": "dist"
  }
}

The dist directory should be added to the project's .gitignore file:

.gitignore

# Build artifacts.
/dist

To ensure your package is published correctly, the following should be set in package.json:

package.json

{
  "files": [
    "dist"
  ],
  "main": "dist/index.js"
}

💡 If you are using the template repository, these are set to the correct values for you by default.

Commit Messages

ts ships with several release scripts that automate the process of determining what kind of semantic version bump (ex: major, minor, patch) to use as well as generating a change log. In order for these scripts to work, a project's commit messages must follow the Conventional Commit specification.

Change logs will be written to a file in the project root named CHANGELOG.md.

Path Mapping & Relative Imports

Path mapping is set up such that src is treated as a root. For example, to import a file at src/lib/utils.ts from anywhere in your project, your import specifier would be:

import utils from 'lib/utils'

This keeps import statements terse and prevents relative path hell.

Tests

Test files should end in .spec.ts or .test.ts and should reside in the src directory alongside source files.