Choosing Typed Racket vs. Untyped Racket: A Practical Decision Guide

What Decision Are We Facing?

In a growing Racket project you may want to add static type safety to catch bugs early, but you also want to keep the dynamic flexibility that Racket is known for. The core decision is whether to write new code in #lang typed/racket or continue with the default #lang racket. The decision is constrained by:

• Safety needs – Do you need compile‑time guarantees for critical modules?
• Performance impact – Will contract checks at typed/untyped boundaries hurt hot loops?
• Migration path – Can you convert modules incrementally?
• Interoperability – How will typed and untyped modules call each other?
• Team skill – Are developers comfortable adding type annotations?

Option Comparison

Feature	Typed Racket	Untyped Racket
Static type checking	✔️ Compile‑time errors for mismatched types, arity, and structure fields.	❌ Only runtime errors.
Runtime contract overhead	✔️ Checks only at module boundaries; inside a typed module no extra overhead.	❌ No overhead, but no early error detection.
Interoperability	✔️ Requires explicit contracts when importing untyped modules; exported functions must be typed.	✔️ Can import typed modules via require/typed or plain require with runtime checks.
Dynamic metaprogramming	❌ Harder to express; many patterns need explicit Any types or struct declarations.	✔️ Full dynamic power; macros and eval work freely.
Performance in hot loops	✔️ No overhead if the loop stays in a typed module.	✔️ No overhead but no early error detection.
Migration effort	❌ Requires type annotations and may need contract wrappers for legacy code.	✔️ Easy to keep legacy code untouched; can add typed wrappers around it.
Learning curve	❌ Requires understanding of Racket’s type system and annotations.	✔️ No new concepts; just dynamic typing.

Key Trade‑offs

1. Safety vs. Flexibility: Typed Racket gives you early guarantees but restricts patterns that rely on dynamic features. If you need to generate code or manipulate arbitrary property lists, you may have to fall back to Any or keep those parts untyped.
2. Performance vs. Overhead: Contracts at the boundary add a small runtime cost. In tight inner loops that stay inside one module, the cost is negligible. If your application calls a typed function from an untyped loop many times per frame, you should benchmark the overhead.
3. Migration Cost vs. Long‑Term Benefit: Converting an entire codebase at once is risky. A gradual, module‑by‑module migration lets you see benefits early while keeping the rest of the system operational.
4. Team Skill vs. Tooling: Typed Racket’s type annotations can improve code readability for experienced developers, but newcomers may find the syntax intimidating. Pairing typed and untyped modules can provide a learning path.

Concrete Migration Example

Below is a minimal scenario that illustrates how to expose a typed function to untyped code and see a contract violation when the wrong type is passed.

1. Create a Typed Module

#lang typed/racket

(provide add-int)

(: add-int (Integer Integer -> Integer))
(define (add-int a b)
  (+ a b))

Save this as typed-add.rkt. The add-int function is declared to take two Integer arguments and return an Integer.

2. Consume it from Untyped Code

#lang racket

(require "typed-add.rkt")

; Correct usage – no error
(displayln (add-int 3 4))

; Incorrect usage – should trigger a contract violation
(displayln (add-int 3 "four"))

Running racket untyped-use.rkt will print the correct sum, then raise a contract error for the second call because the second argument is a string, not an integer. The error appears at runtime, but it is caught before the function body executes.

3. Verify Compile‑time Checking

Run raco typecheck typed-add.rkt. It will succeed because the annotations are correct. If you change the annotation to String but keep the implementation using +, raco typecheck will fail, preventing you from running the program with a type mismatch.

4. Measure Boundary Overhead

To see the cost of crossing the boundary, create two modules that perform the same computation, one entirely in typed Racket, the other split between typed and untyped:

#lang typed/racket

(: sum-loop (Integer Integer -> Integer))
(define (sum-loop n step)
  (let loop ([i 0] [acc 0])
    (if (> i n)
        acc
        (loop (+ i step) (+ acc i)))))

(provide sum-loop)

#lang racket

(require "typed-loop.rkt")

(define (run-typed n step)
  (sum-loop n step))

(define (run-untyped n step)
  (let loop ([i 0] [acc 0])
    (if (> i n)
        acc
        (loop (+ i step) (+ acc i)))))

(define (measure f)
  (let ([t0 (current-inexact-milliseconds)])
    (f 1000000 1)
    (displayln (string-append "time: " (number->string (- (current-inexact-milliseconds) t0)) " ms"))))

(measure run-typed)
(measure run-untyped)

On a typical laptop, you’ll see that run-typed is slightly faster or comparable to run-untyped because the loop stays in a typed module. If you refactor run-typed to call sum-loop from an untyped wrapper, you’ll observe a small overhead per iteration due to the contract check.

Practical Migration Checklist

1. Identify core modules – Pick modules that are stable and benefit most from static checks.
2. Add #lang typed/racket to the module header.
3. Annotate exported functions – Use : annotations for all public signatures.
4. Wrap legacy imports – When a typed module imports untyped code, use require/typed with a contract or keep the import untyped and add a runtime wrapper.
5. Run raco typecheck after each change to catch errors early.
6. Benchmark critical paths – Use time or racket --profile to measure boundary overhead.
7. Iterate – Convert one module at a time, test, and repeat until the desired coverage is reached.

When to Stick with Untyped Racket

• Your code relies heavily on macros that generate arbitrary syntax or manipulate property lists.
• Performance-critical loops call many untyped functions; the contract overhead becomes significant.
• Team members are not ready to learn static typing, and the project timeline is tight.
• You need to maintain a large legacy codebase that would require massive refactor to type.

When Typed Racket Pays Off

• You’re building a library that will be used by others; early error detection improves usability.
• Security or correctness is paramount (e.g., cryptographic code, financial calculations).
• Complex data structures need invariants (e.g., trees, graphs) that can be expressed as contracts.
• Team members are comfortable with type annotations and want better tooling support.

Conclusion

Typed Racket and untyped Racket are not mutually exclusive. By treating them as complementary layers, you can gain the safety of static types where it matters most while preserving the dynamic expressiveness of Racket elsewhere. The trade‑offs boil down to safety versus flexibility, performance overhead versus early error detection, and migration effort versus long‑term maintainability. Use the migration checklist to move incrementally, and benchmark to ensure that boundary checks do not degrade critical performance paths.