ts-backend-check 1.3.1

Check TypeScript interfaces against backend models

Check TypeScript interfaces against backend models

ts-backend-check is a Python package used to check TypeScript types against their corresponding backend models to assure that all fields have been accounted for.

Developed by the activist community, this package is meant to help synchronize the work between frontend and backend development teams. Currently the process supports Django based backends.

Contents

• Usage
  • Command Options
  • Outputs
• Installation
• Configuration
• Contributing
• Environment setup
• Contributors

Usage ⇧

Command Options ⇧

The CLI provides a simple interface to check TypeScript types against backend models:

# Show help and available commands:
ts-backend-check --help
ts-backend-check -gcf  # generate a configuration file
ts-backend-check -gtp  # generate a test project for experimenting with the CLI

# Check a TypeScript type against a backend model:
ts-backend-check -m <model-identifier-from-config-file>
ts-backend-check -a  # run all models

Outputs ⇧

Example success and error outputs for the CLI are:

ts-backend-check -m user
✅ Success: All backend models are synced with their corresponding TypeScript interfaces for the provided files.

ts-backend-check -m user

❌ ts-backend-check error: There are inconsistencies between the provided backend models and TypeScript interfaces. Please see the output below for details.

Field 'user_name' (camelCase: 'userName') from model 'UserModel' is missing in the TypeScript interfaces.
Expected to find this field in the frontend interface: User
To ignore this field, add the following comment to the TypeScript interface: '// ts-backend-check: ignore userName'

Please fix the 1 error above to have the backend models of backend/models/user.py synced with the TypeScript interfaces of frontend/types/user.ts.

Installation

ts-backend-check is available for installation via uv (recommended) or pip.

For Users

# Using uv (recommended - fast, Rust-based installer):
uv pip install ts-backend-check

# Or using pip:
pip install ts-backend-check

For Development Build

git clone https://github.com/activist-org/ts-backend-check.git  # or ideally your fork
cd ts-backend-check

# With uv (recommended):
uv sync --all-extras  # install all dependencies
source .venv/bin/activate  # activate venv (macOS/Linux)
# .venv\Scripts\activate  # activate venv (Windows)

# Or with pip:
python -m venv .venv  # create virtual environment
source .venv/bin/activate  # activate venv (macOS/Linux)
# .venv\Scripts\activate  # activate venv (Windows)
pip install -e .

Configuration ⇧

ts-backend-check is configured via a .ts-backend.check.yaml (or .yml) configuration file, with an example being the configuration file for this repository that we use in testing. The following describes the structure of an entry in this file:

model_identifier: # an identifier you define that you want to pass to the CLI
  backend_model_path: path/to/a/models.py
  ts_interface_path: path/to/the/corresponding/model_interfaces.ts
  check_blank_model_fields: true # whether to assert that fields that can be blank must also be optional
  backend_to_ts_model_name_conversions: # used if the frontend name is not the backend name
    EventModel: [CommunityEvent]

pre-commit ⇧

The following is an example of a prek or pre-commit hook:

- repo: local
  hooks:
    - id: run-ts-backend-check
      name: run ts-backend-check key-value checks
      files: ^src-dir/
      entry: ts-backend-check -a
      language: python
      pass_filenames: false
      additional_dependencies:
        - ts-backend-check

GitHub Action ⇧

The following is an example YAML file for a GitHub Action to check your backend models and TypeScript interface files on PRs and commits:

name: pr_ci_ts_backend_check
on:
  workflow_dispatch:
  pull_request:
    branches:
      - main
    types:
      - opened
      - reopened
      - synchronize
  push:
    branches:
      - main

jobs:
  ts_backend_check:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Project
        uses: actions/checkout@v4

      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Install uv
        uses: astral-sh/setup-uv@v7

      - name: Install Dependencies
        run: uv sync --frozen --all-extras

      - name: Execute All ts-backend-check Key-Value Checks
        run: |
          uv run ts-backend-check -a

Contributing ⇧

activist uses Matrix for internal communication. You're more than welcome to join us in our public chat rooms to share ideas, ask questions or just say hi to the team :) We'd suggest that you use the Element client and Element X for a mobile app.

Please see the contribution guide if you are interested in contributing. Work that is in progress or could be implemented is tracked in the issues and projects.

[!NOTE] Just because an issue is assigned on GitHub doesn't mean the team isn't open to your contribution! Feel free to write in the issues and we can potentially reassign it to you.

Also check the -next release- and -priority- labels in the issues for those that are most important, as well as those marked good first issue that are tailored for first-time contributors. For those new to coding or our tech stack, we've collected links to helpful documentation pages in the contribution guide.

We would be happy to discuss granting you further rights as a contributor after your first pull requests, with a maintainer role then being possible after continued interest in the project. activist seeks to be an inclusive, diverse and supportive organization. We'd love to have you on the team! Please see the mentorship and growth section of the contribution guide for further information.

How you can help ⇧

• Reporting bugs as they're found 🐞
• Working with us on new features ✨
• Documentation for onboarding and project cohesion 📝

Environment setup ⇧

1. First and foremost, please see the suggested IDE setup in the dropdown below to make sure that your editor is ready for development.

[!IMPORTANT]

Suggested IDE setup

VS Code

Install the following extensions:

• charliermarsh.ruff
• streetsidesoftware.code-spell-checker

2. Fork the ts-backend-check repo, clone your fork, and configure the remotes:

[!NOTE]

Consider using SSH

Alternatively to using HTTPS as in the instructions below, consider SSH to interact with GitHub from the terminal. SSH allows you to connect without a user-pass authentication flow.

To run git commands with SSH, remember then to substitute the HTTPS URL, https://github.com/..., with the SSH one, [e-mail]:....

• e.g. Cloning now becomes git clone [e-mail]:<your-username>/ts-backend-check.git

GitHub also has their documentation on how to Generate a new SSH key 🔑

# Clone your fork of the repo into the current directory.
git clone https://github.com/<your-username>/ts-backend-check.git
# Navigate to the newly cloned directory.
cd ts-backend-check
# Assign the original repo to a remote called "upstream".
git remote add upstream https://github.com/activist-org/ts-backend-check.git

• Now, if you run git remote -v you should see two remote repositories named:
  • origin (forked repository)
  • upstream (ts-backend-check repository)

3. Install uv if you don't already have it by following the official installation guide.

4. Create a virtual environment for ts-backend-check (Python >=3.12), activate it and install dependencies:

   uv sync --all-extras  # create .venv and install all dependencies from uv.lock
   
   # Unix or macOS:
   source .venv/bin/activate
   
   # Windows:
   .venv\Scripts\activate.bat  # .venv\Scripts\activate.ps1 (PowerShell)
   

[!NOTE] If you change dependencies in pyproject.toml, regenerate the lock file with the following command:

uv lock  # refresh uv.lock for reproducible installs

5. After activating the virtual environment, set up prek by running:

prek install
# uv run prek run --all-files  # lint and fix common problems in the codebase

You're now ready to work on ts-backend-check!

[!NOTE] Feel free to contact the team in the Development room on Matrix if you're having problems getting your environment setup!

Contributors ⇧

Thanks to all our amazing contributors! ❤️