> For the complete documentation index, see [llms.txt](https://darkobits.gitbook.io/ts/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://darkobits.gitbook.io/ts/conventions.md).

# Conventions

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

### Source Files & Build Artifacts <a href="#source-files-amp-build-artifacts" id="source-files-amp-build-artifacts"></a>

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:

{% code title="tsconfig.json" %}

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

{% endcode %}

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

{% code title=".gitignore" %}

```sh
# Build artifacts.
/dist
```

{% endcode %}

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

{% code title="package.json" %}

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

{% endcode %}

> 💡 If you are using the [template repository](https://github.com/darkobits/ts-template), these are set to the correct values for you by default.

### Commit Messages <a href="#commit-messages" id="commit-messages"></a>

`ts` ships with several release scripts that automate the process of determining what kind of [semantic version](https://semver.org/) 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](https://www.conventionalcommits.org/) specification.

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

### Path Mapping & Relative Imports <a href="#path-mapping-amp-relative-imports" id="path-mapping-amp-relative-imports"></a>

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:

```js
import utils from 'lib/utils'
```

This keeps import statements terse and prevents [relative path hell](https://goenning.net/2017/07/21/how-to-avoid-relative-path-hell-javascript-typescript-projects/).

### Tests <a href="#tests" id="tests"></a>

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