This repository is the home for the TypeScript types for three.js. Periodically the updates from this repository are pushed to DefinitelyTyped and released in the @types/three npm package.
We are using this repository as a home for the types instead of DefinitelyTyped because:
- It is less daunting for users to raise issues or create PRs on a repository that is specific to three.js
- It is easier to organize the process of making sure we're staying up-to-date with the changes in the three.js repository
- It gives us more freedom to use our own process
The highest priority is making sure that there are no inaccurate types (or types for things that have been removed).
It is a goal to have complete public facing API types for all of the code in the src directory.
It is not a goal for the examples/jsm directory to have complete declaration files for every examples module due to the number of example modules and how quickly they are modified. If you would like to use an examples module that is missing types then create a PR to add the types or create an issue to request that we add the missing types for that module.
The tests are split into two directories: types/three/test/integration and types/three/test/unit.
The integration tests are usually runnable three.js code that has just been translated to TypeScript to make sure the types work. The three-examples is a special directory that holds the examples from the three.js repository with matching file names. If you want to add a integration test, you can just create a new file in the integration directory.
The unit tests are more fine-grained tests that focus on testing the types for a single file from the source code (either from the three.js core or the JSM addons). The directory structure of the unit tests matches the directory structure of the source code. These tests often contain type assertions as well to test the result of calling a method or to verify that the types produce an error in certain situations.
Please see our Contributing Guidelines to help you get started. One of the most important things is choosing a branch to start your work on. If the code you want to contribute is for the current release of three it should be based off master. If it is for the next release of three it should be based off dev. You should then aim your merge into the branch you based off.
Thanks goes to these wonderful people (emoji key):
Why are the declaration files in a types/three/ directory and why is there a notNeededPackages.json?
This makes it easier to re-use the testing process used by DefinitelyTyped since they have a check to make sure the types are within a types directory as well a check for notNeededPackages.json. It also makes it possible to use typeRoots in the tsconfig.json so that the three types can be resolved correctly in the tests.