470

I use TypeScript 2 in my project. I'd like to use some js library, but also typings for that library. I can install types with simple npm install @types/some-library. I'm not sure if I should --save or --save-dev them. It seems to me that even DefinetelyTyped GitHub readme kind of mentions both versions, but never explains them. I would think that @types should be in devDependencies, as types are needed for development and aren't used in runtime, but I saw many times @types in just dependencies. I'm confused.

How should I decide whether @types/* goes into dependencies or devDependencies? Are there actually some more or less official instructions?

kamyl
  • 5,938
  • 4
  • 23
  • 29
  • Are you generating a bundle or is this a package that will be used by others? As I see it you only need to make the distinction between `dependencies` and `devDependencies` in the latter case. – Valentin Sep 13 '17 at 18:06
  • 1
    I make some game in js/ts from scratch. I bundle everything with webpack. There's no backend at all atm, but it's possible that I'll wrap it all in Electron to make it standalone some day. I don't think anyone will ever use it as a dependency in their own app, but I guess it could be possible (think of mini games in GTA games; and my game is open source). Still, I want to learn and follow best practices and it's the main reason I make that game. I hope I clarified my use-case well enough. :) – kamyl Sep 14 '17 at 04:55
  • 1
    Yes, it makes sense, just wanted to make sure that my original answer was relevant to your use case. I still think that the distinction between `devDependencies` and `dependencies` is irrelevant when building a bundle, it's something that `create-react-app` enforces [as well](https://stackoverflow.com/a/44872787/1333383) but ultimately it's up to you to choose – Valentin Sep 14 '17 at 09:58

4 Answers4

326

Let's say you're developing a package "A" that have @types/some-module package in devDependencies. For some reason you're exporting the type from @types/some-module:

import { SomeType } from 'some-module';

export default class APackageClass {
  constructor(private config: SomeType) {
    // …       
  }
}

Right now TypeScript consumers of package "A" are unable to guess what SomeType is, since devDependencies of package "A" are not installed.

In that particular case you need to place @types/* package with regular dependencies. For other cases devDependencies are good enough.

Anton Rudeshko
  • 1,039
  • 2
  • 11
  • 20
wookieb
  • 4,099
  • 1
  • 14
  • 17
  • 19
    So you imply that, if I only use the type in implementation, it’s type definition can be `devDependencies`? – Franklin Yu Jan 18 '18 at 06:23
  • 28
    Yes @FranklinYu . As soon as the type appears in declaration file, you need to place it on `dependencies`. Otherwise `devDependencies` is fine – wookieb Jan 26 '18 at 06:52
  • 9
    But a package works for both TS and JS. JS developers doesn't need those types to compile their code. Adding the type definition to `dependencies` will make dependency tree bloated. – Tyler Liu May 21 '20 at 14:21
  • 5
    @TylerLong Correct. It's not perfect but that's reality. Optionally You can also use "optionalDependencies" but I believe at scale it might be very annoying. – wookieb May 22 '20 at 15:32
  • 6
    I suppose that in case I'm developing an end-user application and not a package I can move all the @types/.. into the devDependencies, correct? – Giovanni Patruno Sep 15 '21 at 14:30
  • 2
    @GiovanniPatruno I think so. As long as your application builds properly in the environment that builds it, then you're good. Whether your build environment installs devDependencies before building, and whether it needs those to build your code, may differ depending on your situation but is easy to test and find out. – Phoenix Jan 05 '22 at 23:30
  • @wookieb Is the code snippet you provided a declaration file or a normal .ts file? It seems to contain implementation that's why I asked. It also seems it is a declaration file due to this sentence "For some reason you're exporting the type from @types/some-module...." – Giorgi Moniava Aug 10 '23 at 20:26
  • @GiorgiMoniava it is a regulars ts file. But once it is compiled to .d.ts file the file would still contain import and reference to a type. `import { SomeType } from 'some-module'; export default class APackageClass { constructor(private config: SomeType){} } ` – wookieb Aug 11 '23 at 08:36
  • @wookieb in your comment if that's a .d.ts file, the constructor should be without `{}` no? I also thought your original code snippet in the answer was .d.ts, maybe because of this sentence "For some reason you're exporting the type from @types/some-module..." – Giorgi Moniava Aug 11 '23 at 09:03
  • Yes without `{}`. You're not exporting the type explicitly but using it in the code and compiling to .d.ts cause the type name to exist in .d.ts file therefore every consumer of the package needs to resolve import of it. – wookieb Aug 11 '23 at 09:14
94

If you're just generating a bundle there may be no need to make the distinction between dependencies and devDependencies. This feature of npm is generally useful when publishing a package that can be used by others and you don't want to spam them with redundant dependencies.

There may be other use cases where splitting dependencies can be helpful but unless you have an express need for this, then my advice is to just pick either one and place everything there. It's not difficult to split them afterwards if the need should arise.

A well-known example of this practice IRL is create-react-app, by default the un-ejected boilerplate it creates places everything in dependencies, see this thread and this answer

Valentin
  • 2,772
  • 1
  • 27
  • 40
  • 13
    If you're not publishing the package, that's correct, but if you are, it has nothing to do with development vs. runtime and everything with *what's needed to build this package* vs. *what's needed to use this package*. – Yogu Jun 12 '18 at 07:39
  • 1
    @Yogu That's why I made the distinction in the first place so yes, I completely agree with you – Valentin Jun 12 '18 at 13:28
  • 45
    I disagree with this advice. `devDependencies` are not installed when you do `npm install --production` (or `npm ci --production`) and thus not available when running production code. This is a very meaningful difference for a service, not just a library. – Brad Wilson Apr 17 '19 at 17:37
  • 3
    @BradWilson You have a point, there are many npm workflows under the sun, if your use case requires you to make the distinction then by all means, do it. Feel free to provide your own answer to this dilemma. – Valentin Apr 17 '19 at 18:57
  • 1
    I've updated my answer to mention the existence of other use cases where the distinction may be meaningful and gave real world examples. Thanks for the feedback! – Valentin Dec 02 '19 at 17:29
  • 1
    It depends on the stack. For example, I think when working with NextJS, using `devDependencies` is important for bundle size – nth-chile Aug 23 '20 at 10:25
43

In the particular case of deploying a Node.js application to production, one wants to install only the dependencies needed to run the application.

npm install --omit=dev or

npm ci --production or

yarn --production

In that case, the types should be in the devDependencies, to keep them from bloating the installation.

(To avoid misunderstandings, the --production or --omit=dev option must not be used on machines where the application is built, otherwise the TypeScript compiler will complain.)

Remarks: I'm aware this was mentioned in a comment by Brad Wilson to another answer. This point seems worthy to be an answer, though.

xinthose
  • 3,213
  • 3
  • 40
  • 59
Carsten Führmann
  • 3,119
  • 4
  • 26
  • 24
  • 1
    I am developing an app using 3rd party libs, put all of the @types/* packages in devDependencies, but then production build fails as typescript is looking for these types in the production build. – omerts Feb 06 '22 at 17:06
  • @omerts: When you wrote "looking for these types in the production build", did you mean "looking for these types in the package.json during compilation"? I'm asking because a production build is what's run on the target machine, and it would be strange if the TypeScript compiler were invoked at that stage. If on the other hand you were talking about compilation on a _developer_ machine, the `devDependencies` should still exist at that stage, because `--production` should only be used when installing for production - not on the developer machine. – Carsten Führmann Feb 07 '22 at 11:02
  • When running yarn/npm install with the production flag on, and then yarn build, either in a CI or docker env, the typescript compiler will fail due to missing types. – omerts Feb 07 '22 at 18:03
  • The issue seems to be that you use the `--production` option already on machines where the application is built. Instead, the option should be used only on machines where the application is run, not built. I clarified my main answer in that regard. – Carsten Führmann Feb 08 '22 at 10:42
  • thanks for the clarification, why would you want to run npm/yarn install on machines where the application is only run? – omerts Feb 09 '22 at 11:05
  • 2
    @omerts While it is sometimes possible to copy the node modules from the build machine the hosts (i.e. the machines that run the application), this seems like a questionable practice, because: Even if the Node.js version number on the hosts is identical to that of the build machine, the target machines might be a different OS. For example, you may develop on Windows, but run things on Linux. And there are cases where e.g. the output of `npm install` on Windows is not correct on Linux. – Carsten Führmann Feb 09 '22 at 11:57
1

Other answers made great sense, but I'm gonna add that a peerDep's type declaration package should also be placed in dependencies instead of peerDependencies.

Assume that b is a plugin of a. And c uses a and b.

Why shouldn't @types/a be placed in b's peerDependencies?

If b's package.json is like:

{
  "peerDependencies": {
    "a": "1.5.x"
    "@types/a": "1.4.x"
  }
}

c may use only interfaces defined in @types/a@1.2.x but c is forced to install @types/a@1.4.x.

Furthermore, c may be a regular javascript package rather than typescript package, but c is also forced to install @types/a@1.4.x.

So, the correct package.json of b should be like:

{
  "peerDependencies": {
    "a": "1.5.x"
  },
  "dependencies": {
    "@types/a": "1.4.x"
  }
}
Zim
  • 1,528
  • 1
  • 10
  • 6