build: Enable TypeScript type checking by camdecoster · Pull Request #7680 · plotly/plotly.js · GitHub

Description

Enable TypeScript type checking.

Part of #7678.

Changes

Add set of plotly.js types
Enable type checking
Update some files to TypeScript
Use ts-node for running some scripts
Add type generation script that uses attributes files schema
Add type checking steps to CI

Testing

CI should cover everything
Run npm run build locally to check that everything is bundled properly by esbuild
Run npm run schema to recreate the generated types
Run plotly.js devtools and load some mocks to make sure everything is working correctly
Run npm run typecheck to perform a type check on the source code. There should be no errors:
```
$ npm run typecheck

> plotly.js@3.5.1 typecheck
> tsc --noEmit
$
```

Notes

This PR adds the TypeScript compiler and typechecking via npm script
The provided types are a combination of plotly.js types from DefinitelyTyped and the schema (with Claude combining the two). This is a first pass and the types will need to be updated as files are converted.
Most of the types are now built straight from the schema
(Most) IDEs will read the types and provide autocompletion once files are converted over
Read the README in src/types for an overview of how the types are set up
esbuild is compatible with TypeScript already, but it doesn't do type checking. To check types you need to run npm run typecheck. VS Code will also provide feedback as you're editing files.
I converted a few simple files to TypeScript as an example. I opted to use ESM syntax for these files which necessitated some changes in the require statements for the converted files. This is due to how esbuild determines if a default import should be namespaced or not.
Some of the converted files are used in scripts not processed by esbuild. Node 18 doesn't handle TS files natively, so these scripts need to be run with ts-node, a "TypeScript execution and REPL for node.js".
The TS config is pretty lenient right now to make it easier to convert things piece by piece. Once we make enough progress, this can be tightened up.
TS is not emitting files/types right now. esbuild handles converting the TS so the TS compiler won't need to do that. It would be valuable to have the compiler write the type definition files in the future.
There's an entry point for types now. It points to the public types, which are a subset of all types. In the future, there could be a type build step that compiles them down to a flat file.

@camdecoster Is it worth considering moving away from default exports entirely as part of this transition?

It only matters when one mixes CJS and ESM. That said, I don't think that we can avoid that for a long time. I suppose we could make just pick a direction to go and standardize. I could go either way, but the esbuild docs make it clear that they don't like default exports.

There's an issue that covers converting from CJS to ESM in #7119. I left a comment mentioning your suggestion.

Does TypeScript have any support for 'flag list'-type string values such as this, where the string may consist of any number of a fixed set of values joined by a delimiter? I suppose not as it's fairly custom.

Otherwise could we use a custom type or a custom function to generate these lists of allowed values based on the flags?

Yes, it's called a union type. What's shown on 133 is an example of that (though it's only used on that line). If we needed that type elsewhere, we could define it separately and reference it within the ScatterTrace type like this:

type Mode = 'lines' | 'markers' | 'lines+markers' | 'none' | 'text' | 'lines+text' | 'markers+text' | 'lines+markers+text';

export interface ScatterTrace extends TraceBase {
    ...,
    mode: Mode;
    ...,
}

Yeah I guess I'm imagining something like a helper function which looks like flagList(flaglistVals, otherVals) such that

flaglistVals(['lines', 'markers', 'text'], ['none'])

returns

'lines' | 'markers' | 'lines+markers' | 'none' | 'text' | 'lines+text' | 'markers+text' | 'lines+markers+text';`

I'm not sure there are any traces where x/y/z are allowed to be a type other than number[] | string[] but I could be wrong about that.

That's why it's permissive here. Once we become sure, we can change this as you suggest.

In this case maybe it would be easier to start stricter and loosen if needed?

Actually, scratch that

@camdecoster Can you add a type-check step to the CI?

Can we tighten this layout spec here to match the plot schema?

@camdecoster Some initial thoughts on organization of the types:

For types corresponding directly to the schema:

Group them all under a single directory (e.g. types/core/schema/), maybe even in a single file if not too unwieldy
Use nested types where useful for repeated patterns (e.g. font options); these should use some kind of consistent naming scheme

Great work! The implementation is clean and easy to understand

Is this needed if there's no output?

Oh never mind, I guess this config file is used by esbuild as well?

It is used by esbuild, but there are some options (including this one) that don't get used. I'll remove them.

This really should be called TraceType... the question is, is it worth breaking correspondence with DefinitelyTyped to use the semantically correct type name?

I think we can do whatever we want. I'm less interested in maintaining the DT API since I started using the schema as the source of truth. I'll look into the possibility of changing the name.

@camdecoster I think it would be useful to add guidance for converting non-attributes files as well, or at least guidance on which files are the highest-priority to convert and which ones don't need to be touched. But again that doesn't need to be blocking for merge.

Left a bunch of nitpicky comments but big picture LGTM.

Co-authored-by: Emily KL <4672118+emilykl@users.noreply.github.com>

…cript-type-checking

camdecoster changed the title build: Enable typescript type checking build: Enable TypeScript type checking Jan 2, 2026

camdecoster marked this pull request as ready for review January 2, 2026 23:54

camdecoster requested a review from emilykl January 7, 2026 16:57

camdecoster assigned emilykl Jan 7, 2026

emilykl reviewed Jan 12, 2026

View reviewed changes

emilykl reviewed Jan 13, 2026

View reviewed changes

emilykl reviewed Jan 15, 2026

View reviewed changes

archmoj mentioned this pull request Jan 27, 2026

Set default layout.axis.tickmode to 'sync' when axis is overlaying #7684

Merged

codeCraft-Ritik reviewed Feb 28, 2026

View reviewed changes

camdecoster assigned camdecoster and unassigned emilykl Apr 15, 2026

camdecoster added 9 commits May 5, 2026 16:28

Linting/formatting

51001fd

Initial TS set up

cef04d2

Convert a few small files to TS

412d4b1

Update requires to handle esbuild ESM/CJS interoperability

f704542

Use ts-node for scripts using TS that run outside of esbuild

5f72cf8

Run test script with ts-node

5ed7da0

Add additional types and type generation script

f2622c5

Convert modebar attributes to TS

a131cfe

Add type generation npm scripts

de168ca

camdecoster force-pushed the cam/7678/enable-typescript-type-checking branch from 2439dad to de168ca Compare May 6, 2026 22:07

camdecoster added 5 commits May 6, 2026 16:13

Add type check steps to CI

5f8654c

Update TS docs

eebf71e

Add entry point to types

c11bca1

Update file name case check

04261b2

Linting/formatting

e69463a

camdecoster requested a review from emilykl May 7, 2026 16:07