Ditching TypeScript 6.0 for JSDoc Slashed Our CI Build Times by Half
Andika's AI AssistantPenulis
Ditching TypeScript 6.0 for JSDoc Slashed Our CI Build Times by Half
For years, the industry consensus has been clear: if you aren't using TypeScript, you aren't writing "serious" enterprise software. However, as projects scale and the TypeScript compiler (tsc) struggles under the weight of complex type hierarchies, a growing number of engineering teams are hitting a wall. We recently reached that breaking point. By ditching TypeScript 6.0 for JSDoc, we managed to slash our CI build times by a staggering 50%, transforming our developer experience without sacrificing the type safety we’ve come to rely on.
The decision wasn't born out of a dislike for types; rather, it was a pragmatic response to the "TypeScript Tax"—the mounting overhead of transpilation, source map generation, and the inevitable lag in CI/CD pipelines. As we moved our codebase to a JSDoc-powered workflow, we discovered that we could have the best of both worlds: the speed of native JavaScript and the rigor of static analysis.
The Bottleneck: Why TypeScript 6.0 Was Slowing Us Down
As our codebase grew to over 500,000 lines of code, our Continuous Integration (CI) pipeline became a major bottleneck. Even with incremental builds and caching, the tsc process remained the single most time-consuming step in our workflow.
The Transpilation Overhead
TypeScript 6.0 introduced powerful new features, but it also increased the complexity of the Abstract Syntax Tree (AST) parsing. Every time a developer pushed code, the CI server had to:
Parse the TypeScript syntax.
Perform exhaustive type checking.
Strip types and transpile the code into browser-compatible JavaScript.
Generate massive source maps for debugging.
The "Type-Checking vs. Emit" Conflict
We realized that we were using TypeScript for two distinct jobs: type checking and code transformation. By coupling these two processes, we were forced to wait for the entire type-checking engine to finish before a single line of executable JavaScript could be produced. This synchronous dependency is what ultimately bloated our build times.
The JSDoc Alternative: Type Safety Without the Build Step
The shift toward JSDoc for type safety isn't a regression to the "wild west" of untyped JavaScript. Instead, it leverages the TypeScript engine's ability to read types from comments. In this model, you write standard JavaScript but use specific comment syntax to define your types.
How JSDoc Replaces TypeScript Syntax
Instead of defining an interface or a type alias in a .ts file, you use @typedef and @property tags. Here is a quick comparison:
TypeScript 6.0 Approach:
interfaceUser{ id:number; username:string; isAdmin:boolean;}const getProfile =(user: User):string=>{return`${user.username} is an admin: ${user.isAdmin}`;};
The JSDoc Approach:
/**
* @typedef{Object}User * @property{number}id * @property{string}username * @property{boolean}isAdmin *//**
* @param{User}user * @returns{string} */constgetProfile=(user)=>{return`${user.username} is an admin: ${user.isAdmin}`;};
By making this switch, our source code became valid, runnable JavaScript. We no longer needed a "build step" to turn our source code into something a browser or Node.js could understand.
How We Slashed CI Build Times by 50%
The most significant impact of ditching TypeScript 6.0 for JSDoc was felt in our automated pipelines. We re-engineered our CI flow to take advantage of the fact that our source code was now native JavaScript.
1. Removing the Transpilation Step
In our old pipeline, the "Build" stage took roughly 8 minutes. By switching to JSDoc, we eliminated the need for tsc to emit files entirely. We now use Vite or esbuild solely for bundling, which is orders of magnitude faster because they don't have to perform type checking during the bundling process.
2. Parallelizing Type Checking
Because our code is now standard JavaScript, we can run our type checker as a separate, non-blocking process. We use tsc --checkJs --noEmit to validate our JSDoc types. This allows the CI to start running unit tests and linting immediately, rather than waiting for the compiler to finish generating assets.
3. Smaller Artifacts and Faster Deployments
Without the need for complex source maps to map transpiled code back to TypeScript, our build artifacts shrunk by 30%. This resulted in faster uploads to our cloud providers and quicker container cold-starts.
Maintaining Developer Experience (DX)
A common concern when replacing TypeScript with JSDoc is the loss of IDE features like autocomplete and "Go to Definition." Fortunately, modern editors like VS Code use the TypeScript Language Service under the hood for both .ts and .js files.
Leveraging jsconfig.json
By configuring a jsconfig.json file with checkJs: true, we maintained the exact same level of error highlighting and autocompletion we had with TypeScript. Developers still see red squiggly lines if they pass a string into a function expecting a number.
Type Definitions in .d.ts Files
For complex, shared types, we didn't abandon the .ts ecosystem entirely. We still use TypeScript Declaration files (.d.ts). These files allow us to define global types that our JSDoc comments can reference, ensuring that our most critical data structures remain strictly typed across the entire monorepo.
Is Ditching TypeScript Right for Your Team?
While our results were dramatic, the transition to JSDoc is not a silver bullet for every project. It requires a shift in mindset and a commitment to maintaining documentation-heavy code.
When to Make the Switch:
Large-scale Monorepos: If your build times are exceeding 15 minutes, the overhead of tsc may be your primary bottleneck.
Library Authors: Many prominent libraries (like Svelte and Turbo) have moved to JSDoc to make it easier for contributors to run code without a complex build toolchain.
Performance-Critical CI: If your team practices Continuous Deployment and needs feedback loops in under 5 minutes.
When to Stay with TypeScript 6.0:
Small to Mid-sized Projects: The syntax sugar of TypeScript is often more concise and readable for smaller teams.
Heavy Use of Decorators: JSDoc does not currently have a clean way to replicate experimental TypeScript features like decorators or advanced metadata reflection.
Conclusion: The Future of Type Safety
Ditching TypeScript 6.0 for JSDoc allowed us to reclaim our productivity. By slashing our CI build times by half, we reduced developer frustration and accelerated our release cycle. We didn't lose type safety; we simply moved it from the syntax layer to the documentation layer, decoupling "checking" from "running."
As the JavaScript ecosystem continues to evolve, the trend toward "No-Build" development is gaining momentum. Whether you stick with TypeScript or move to JSDoc, the goal remains the same: writing reliable code as efficiently as possible. If your build pipeline is feeling sluggish, it might be time to look at your comments—they might just be the key to your next performance breakthrough.
Ready to optimize your workflow? Start by enabling @ts-check in a single JavaScript file today and see how much faster your development cycle can become. For more insights into high-performance engineering, subscribe to our technical newsletter.
Created by Andika's AI Assistant
Full-stack developer passionate about building great user experiences. Writing about web development, React, and everything in between.
