TypeScript Config

TypeScript Config (hereinafter the “Application”) is a shareable TypeScript compiler configuration package designed to enforce strict type checking and consistent coding standards across multiple TypeScript projects. The Application provides a pre-configured tsconfig.json that can be extended by other projects to maintain code quality and catch potential errors during development.

1. User Documentation

This section is for those interacting with a live instance of the Application.

1.1. Overview

The Application is a published npm package (@nhcarrigan/typescript-config) that provides a standardised TypeScript configuration. It enforces strict typing rules and modern ECMAScript standards to improve code quality and maintainability.

1.2. Installation

To install the Application in your project, use the following command:

npm i @nhcarrigan/typescript-config typescript

Or with pnpm:

pnpm add @nhcarrigan/typescript-config typescript

1.3. Usage

After installation, extend the Application’s configuration in your project’s tsconfig.json file:

{
  "extends": "@nhcarrigan/typescript-config",
  "compilerOptions": {
    "rootDir": "./src",
    "outDir": "./prod"
  }
}

Important Notes:

• You must specify rootDir and outDir in your project’s tsconfig.json as these are not set by default in version 4.0.0 and above
• Set these directories to match your project’s structure
• The Application is compatible with TypeScript 5 and above

1.4. Configuration Features

The Application provides the following compiler options:

Target and Module System

• Target: ES2022 - Compiles code to ECMAScript 2022 standard
• Module: ES2022 - Uses ES2022 module system
• Module Resolution: Node - Uses Node.js module resolution strategy

Type Safety

• Strict Mode: Enabled - Enforces all strict type-checking options
• Exact Optional Property Types: Enabled - Distinguishes between undefined and absent properties
• No Unchecked Indexed Access: Enabled - Adds undefined to index signature results
• No Implicit Returns: Enabled - Ensures functions return values consistently

Code Quality

• No Unreachable Code: Disallowed - Prevents dead code
• No Unused Labels: Disallowed - Prevents unused labels
• No Fallthrough Cases in Switch: Enabled - Requires explicit fallthrough in switch statements
• No Implicit Override: Enabled - Requires explicit override keyword
• No Unused Locals: Enabled - Reports unused local variables
• No Unused Parameters: Enabled - Reports unused function parameters

Interoperability

• ES Module Interop: Enabled - Improves compatibility with CommonJS modules
• Skip Lib Check: Enabled - Skips type checking of declaration files
• Force Consistent Casing in Filenames: Enabled - Ensures case-sensitive file imports

1.5. Package Information

• Version: 4.0.0
• NPM Package: @nhcarrigan/typescript-config
• Author: Naomi Carrigan
• License: Global Software Licence

1.6. Support and Feedback

• Issues: Report bugs at GitHub Issues
• Contact: Available via Chat Server or email at [email protected]

2. Technical Documentation

This section is for those interested in running their own instance of the Application.

2.1. Project Structure

The Application has a minimal structure focused on distributing a TypeScript configuration:

typescript-config/
├── src/
│   └── index.ts          # Test file for validating configuration
├── tsconfig.json         # The main configuration file
├── package.json          # Package metadata and dependencies
└── [documentation files] # README, LICENSE, CONTRIBUTING, etc.

2.2. Source Code

Configuration File (tsconfig.json:1)

The main configuration file exports the following compiler options:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "Node",
    "allowUnreachableCode": false,
    "allowUnusedLabels": false,
    "exactOptionalPropertyTypes": true,
    "noFallthroughCasesInSwitch": true,
    "noImplicitOverride": true,
    "noImplicitReturns": true,
    "noUncheckedIndexedAccess": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  }
}

Test File (src/index.ts:1)

The source directory contains a minimal test file used to validate that the configuration compiles correctly:

(async () => {
  console.log("just testing!");
})();

This file serves as a smoke test to ensure the TypeScript configuration is valid.

2.3. Development Setup

Prerequisites

• Node.js version 20
• pnpm version 9
• TypeScript >= 5.5.2 (peer dependency)

Local Development

1. Clone the repository:

git clone https://github.com/spellware/typescript-config.git
cd typescript-config

2. Install dependencies:

pnpm install

3. Run tests:

pnpm test

The test script runs the TypeScript compiler with specific rootDir and outDir settings to validate the configuration.

2.4. Build and Test Process

The Application uses a simple test script defined in package.json:6:

tsc --rootDir './src' --outDir './prod' && echo 'build appears valid!'

This command:

1. Compiles TypeScript files from the src directory
2. Outputs compiled JavaScript to the prod directory
3. Confirms successful compilation with a success message

2.5. Publishing

The Application is published to npm under the package name @nhcarrigan/typescript-config. The main entry point is the tsconfig.json file itself (as specified in package.json:5).

2.6. Version History

The current version is 4.0.0, which introduced breaking changes:

• Removed default rootDir and outDir settings
• Users must now explicitly set these in their project’s tsconfig.json
• This change resolves incompatibilities with certain package managers

2.7. Design Decisions

The configuration emphasises:

1. Strict Type Checking: All strict options are enabled to catch potential errors at compile time
2. Modern JavaScript: Targets ES2022 for modern language features
3. Code Quality: Enforces best practices like no unused variables, no unreachable code
4. Flexibility: Allows projects to specify their own directory structure (rootDir/outDir)

3. Legal Documentation

This section is for expansions to our legal policies specific to the Application.

3.1. License

The Application is licensed under the Global Software Licence. Copyright is held by Naomi Carrigan.

See LICENSE.md for full licence details.

3.2. Terms of Service

Users of the Application are subject to the global Terms of Service available at https://docs.spellware.dev/#/terms.

See TERMS.md for reference.

3.3. Privacy Policy

The Application does not collect or transmit any user data. For general privacy policies, refer to https://docs.spellware.dev/#/privacy.

See PRIVACY.md for reference.

3.4. Security Policy

Security vulnerabilities should be reported according to the guidelines at https://docs.spellware.dev/#/security.

See SECURITY.md for reference.

3.5. Intellectual Property

The Application’s configuration is an original work created by Naomi Carrigan. The specific combination of TypeScript compiler options represents curated decisions for code quality and safety.

4. Contributing Documentation

This section is for documentation related to contributing to the Application’s codebase.

4.1. Contributing Guidelines

Comprehensive contributing guidelines are available at https://docs.spellware.dev/#/contributing.

See CONTRIBUTING.md for reference.

4.2. Code of Conduct

Before interacting with the community, please review the Code of Conduct available in CODE_OF_CONDUCT.md.

4.3. How to Contribute

Reporting Issues

If you encounter bugs or have feature requests:

1. Check existing issues at GitHub Issues
2. Create a new issue with a clear description
3. Include TypeScript version and package manager information

Submitting Changes

1. Fork the repository
2. Create a feature branch
3. Make your changes to the configuration
4. Test that the configuration compiles correctly (pnpm test)
5. Submit a Pull Request with a clear description of changes
6. Await review from maintainers

Configuration Changes

When proposing changes to the TypeScript configuration:

• Explain the rationale for the change
• Document any breaking changes
• Consider backward compatibility
• Test with various TypeScript projects to ensure compatibility

4.4. Development Workflow

1. Clone the repository
2. Create a branch for your changes
3. Modify tsconfig.json as needed
4. Run pnpm test to validate changes
5. Update documentation if necessary
6. Commit with clear, descriptive messages
7. Submit a Pull Request

4.5. Testing Changes

To test configuration changes:

1. Make modifications to tsconfig.json
2. Run the test script: pnpm test
3. Test in a real project by linking locally:

   # In this package directory
   pnpm link
   
   # In your test project
   pnpm link @nhcarrigan/typescript-config

4. Verify the configuration works as expected

4.6. Repository Information

• Repository: https://github.com/spellware/typescript-config
• Issue Tracker: https://github.com/spellware/typescript-config/issues
• Git URL: [email protected]:nhcarrigan/typescript-config.git

4.7. Contact

For questions about contributing:

• Join the Chat Server
• Email: [email protected]