A Reasonable Way to Write TypeScript

Why Another Style Guide?

If you're a JavaScript or TypeScript developer, you're likely familiar with style guides like Airbnb's popular JavaScript guidelines. These guides help keep code clean and consistent. But why create another one specifically for TypeScript? Simply put, TypeScript offers unique features and challenges, that standard JavaScript guides might not fully address.

The Mozayk TypeScript Style Guide takes inspiration from established guides but focuses explicitly on TypeScript's strengths, like robust typing, modern syntax and built-in safeguards. Rather than patching TypeScript onto an existing JavaScript framework, Mozayk's guide is TypeScript-first from the ground up.

Plus, it's also AI-friendly, structured to be easily parsed and followed by AI agents or code-generation tools, making it a great fit for modern workflows that include automated refactoring or agentic-style assistance.

Philosophy and Core Principles

Mozayk's style guide emphasizes three main things: safety, consistency and developer happiness. Here's what that looks like in practice:

Type Safety Above All

Prioritizes strict type safety. This means actively avoiding any types unless truly necessary and mandating explicit handling of promises. Using TypeScript fully helps eliminate common bugs upfront.

Consistency without Nitpicking

Consistent code makes teamwork smoother. Incorporates widely-accepted conventions, such as single quotes for strings, two-space indentation and trailing commas for clearer diffs. Predefined guidelines reduce unnecessary debates, letting teams focus on real code issues.

Embracing Modern TypeScript

Recommends modern TypeScript practices. It avoids outdated patterns, such as namespaces, favoring modern modules instead. It promotes using as const assertions and avoids known JavaScript pitfalls, like using for-in loops incorrectly. These modern guidelines future-proof your projects.

Automated Formatting with ESLint & Prettier

Relies heavily on automation, integrating ESLint for logic and correctness alongside Prettier for consistent formatting. This combo eliminates manual style adjustments, allowing developers to concentrate on writing robust logic.

React-Friendly and Modular

Includes specific guidelines for React projects, covering common issues like accessibility checks and hook usage. Non-React projects simply omit React guidelines, keeping configurations flexible and relevant.

Inspired by Community

Integrates proven best practices from popular open-source style guidelines. Every guideline is justified clearly, ensuring they aren't arbitrary but purposeful and helpful.

What's Included?

Mozayk's style guide provides:

• Complete ESLint Configuration: Covering TypeScript-specific guidelines and best practices to prevent bugs early.
• Prettier Configuration: Automatically formats code, enforcing a clean style (two-space indentation, single quotes, trailing commas and 100-character line length).
• React/JSX Configurations: Includes guidelines to manage React-specific scenarios like hooks and accessibility, ensuring front-end code stays clean.
• Modularity: Packages are separated by functionality, so teams can easily adopt what they need without unnecessary guidelines.
• Always Current: Supports the latest standards, including ESLint v9, Prettier v3 and TypeScript v5, ensuring compatibility with emerging tech.

Getting Started

To implement Mozayk's guide in your project:

1. Installation

Install Mozayk configurations and dependencies via npm or yarn:

npm install --save-dev \
  @mozayk/eslint-config-base \
  @mozayk/eslint-config-typescript \
  @mozayk/eslint-config-react \
  @mozayk/prettier-config \
  @typescript-eslint/eslint-plugin@^8 \
  @typescript-eslint/parser@^8 \
  eslint@^9.7 \
  eslint-import-resolver-typescript@^4 \
  eslint-plugin-import@^2.31 \
  eslint-plugin-jsx-a11y@^6.10 \
  eslint-plugin-react@^7.35 \
  eslint-plugin-react-hooks@^5 \
  prettier@^3 \
  typescript@^5.8

2. ESLint Setup

In your eslint.config.js, import and apply Mozayk configs:

import mozaykBaseConfig from '@mozayk/eslint-config-base';
import mozaykTypeScriptConfig from '@mozayk/eslint-config-typescript';
import mozaykReactConfig from '@mozayk/eslint-config-react';
import * as typescriptParser from '@typescript-eslint/parser';
import globals from 'globals';

/** @type {import("eslint").Linter.Config[]} */
export default [
  ...mozaykBaseConfig,
  ...mozaykTypeScriptConfig,
  ...mozaykReactConfig,
  {
    languageOptions: {
      parser: typescriptParser,
      parserOptions: {
        ecmaFeatures: { jsx: true },
        jsxPragma: null,
        sourceType: 'module',
        projectService: true,
      },
      globals: {
        ...globals.browser,
        ...globals.es2022,
        ...globals.node,
        React: 'writable',
        JSX: 'readonly',
      },
    },
    rules: {
      // Your custom rules here
    },
  },
];

Adjust configs as needed depending on project specifics.

3. Prettier Setup

In prettier.config.js, import Mozayk Prettier config:

import mozaykPrettierConfig from '@mozayk/prettier-config';

/** @type {import("prettier").Config} */
export default {
  ...mozaykPrettierConfig,
  // Your custom rules here
};

Add scripts to package.json for easy linting and formatting:

{
  "scripts": {
    "lint": "eslint . --max-warnings=0",
    "format": "prettier . --write"
  }
}

Feedback & Community

Mozayk TypeScript Style Guide was built to streamline development, minimize arguments and ensure high-quality, consistent code. It's open-source under the MIT license and available on GitHub. Your feedback helps to improve it, so give it a try and share your thoughts!