typescript-source-organization

Source Organization

Apply the TypeScript Style Guide's source organization conventions in the context of the current task.

Workflow

1. Inspect the consuming repository's existing structure, framework conventions, and configuration.
2. Let explicit repository conventions take precedence over this opinionated guidance.
3. Apply, review, or explain only the guidance relevant to the task.
4. State important tradeoffs when organization depends on project size, framework, or team conventions.

Boundaries

• Keep formatting and linting tools responsible for import sorting when configured.
• Do not reorganize unrelated files merely because this skill is active.

Source Organization

Code Collocation

• Every application or package in a monorepo has project files and folders organized and grouped by feature.
• Collocate code as close as possible to where it's relevant.
• Deep folder nesting should not represent an issue.

Imports

Import paths can be relative, starting with ./ or ../, or they can be absolute @common/utils.

To make import statements more readable and easier to understand:

• Relative imports ./sortItems must be used when importing files within the same feature that are 'close' to each other. This also allows moving the feature around the codebase without changing these imports.
• Absolute imports @common/utils must be used in all other cases.
• All imports must be auto sorted by tooling e.g. prettier-plugin-sort-imports, eslint-plugin-import etc.

// ❌ Avoid
import { bar, foo } from '../../../../../../distant-folder';

// ✅ Use
import { locationApi } from '@api/locationApi';

import { foo } from '../../foo';
import { bar } from '../bar';
import { baz } from './baz';

Project Structure

Example frontend monorepo project where every application has files and folders grouped by feature: