FG
🔌 APIs & SDKs

Road to Typescript

Freshabout 20 hours ago
Mar 14, 20260 views
Confidence Score95%
95%

Problem

This is an issue is to discuss our plan to convert this library to TypeScript. Note: We will still continue to provide full Flow typings in the same package. This effort is in line with the ongoing conversion of GraphQL IDE packages (GraphiQL, GraphQL LSP, etc.): https://github.com/graphql/graphiql/tree/convert-to-ts Note this decision is not related to the technical aspect of Flow vs TS. GraphQL.js has complete Flow coverage and it is excellent for ongoing maintenance. But our goal is to increase the number of active contributors and by switching codebase to TypeScript we hope to make the codebase feel more familiar and easy to contribute to. Big thanks to @JacksonKearl from Apollo team for making PoC for such conversion and exploring different conversion strategies. Before we start discussing the action plan here is a few important points: `14.x.x` is stable release so we shouldn't do any potentially breaking things in this release. We need to do `15.0.0` anyway since it becomes hard to maintain support for Node6 since ESLint and other projects stop supporting it. Plus it allows us simply remove all deprecated stuff that was scheduled for removal in this release. Even after we release `15.0.0` we will still need to support `14.x.x` as a branch and backport all critical or security-related bugfixes until `16.0.0`. Giving these constraints here is a plan I want to propose: - [x] 1. Freeze all non-critical merges for the duration of this conversion - [x] 2. I copied al

Unverified for your environment

Select your OS to check compatibility.

1 Fix

Canonical Fix
Unverified Fix
New Fix – Awaiting Verification

Plan for Converting Library to TypeScript

Medium Risk

The library currently uses Flow for type checking, which may deter potential contributors who are more familiar with TypeScript. The goal is to transition to TypeScript to enhance contributor engagement while maintaining Flow typings for existing users.

Awaiting Verification

Be the first to verify this fix

  1. 1

    Freeze Non-Critical Merges

    To ensure stability during the conversion process, freeze all non-critical merges to the main branch. This will prevent any potential conflicts or breaking changes while the TypeScript conversion is underway.

    bash
    git branch --set-upstream-to=origin/main
  2. 2

    Create a TypeScript Branch

    Create a new branch specifically for the TypeScript conversion. This will allow for isolated development and testing of the TypeScript codebase without affecting the stable release.

    bash
    git checkout -b convert-to-typescript
  3. 3

    Implement TypeScript Configuration

    Set up the TypeScript configuration file (tsconfig.json) to define the compiler options and include/exclude patterns for the TypeScript files. This will ensure that the TypeScript compiler behaves as expected.

    json
    {
  "compilerOptions": {
    "target": "es6",
    "module": "commonjs",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}
  4. 4

    Convert Files to TypeScript

    Gradually convert existing JavaScript files to TypeScript (.ts) files. Start with core files and ensure that Flow typings are preserved in the same package. This can be done file by file to manage complexity.

    typescript
    // Example of converting a file
function greet(name: string): string {
  return `Hello, ${name}!`;
}
  5. 5

    Test TypeScript Integration

    Run tests to ensure that the TypeScript conversion does not introduce any regressions. Use existing test suites and add new tests as necessary to cover TypeScript-specific features.

    bash
    npm run test
  6. 6

    Document the Conversion Process

    Create documentation outlining the conversion process, including any challenges faced and how they were resolved. This will help future contributors understand the changes made and how to contribute effectively.

    markdown
    // Documentation should include:
// - Overview of TypeScript benefits
// - Steps taken during conversion
// - How to contribute with TypeScript

Validation

Confirm the fix by ensuring that the TypeScript branch compiles without errors and passes all existing tests. Additionally, gather feedback from contributors to assess if the TypeScript codebase is more approachable.

Sign in to verify this fix

Environment

Submitted by

AC

Alex Chen

2450 rep

Tags

graphqlapischemadiscussion