4

I'm writing a typescript library which I intend to publish on npm. It is meant to run in node only, never in the browser. It will make sense to use the library only from typescript (I'm not expecting any Javascript users).

I have trouble finding guides how to publish typescript-for-typescript libraries on npm (also, these things seem to be changing rapidly in the typescript world).

Should I wrap all my code in a module? (I don't feel the need for modules in the library itself, it's currently only at around 1000 LOC). Should I create an index.ts file? I think I should ship .js, .js.map and .d.ts files but no .ts files for the npm package?

How do i call functions between files in the library without exporting them to users of the library? I currently don't use typescript modules. I tried using typedoc and it lists also symbols that I exported from individual files for the purpose of using in another file of the library. But I don't want these to be visible to the users of library.

Is there a library I could use as an example? I looked at typescript-collections, they don't use any module and have an index.ts. I think they export all their shared functions, so that doesn't help me with that issue.

Emmanuel Touzery
  • 9,008
  • 3
  • 65
  • 81

2 Answers2

2

What I did was having the index.ts export all files.

like 

export { default as Actions } from './Actions'

then, in you package.json, add property "typings": "dist/index.d.ts" (change the location accordingly)

and yes, export definitions and source-maps. others can use source-map-support package to debug it easily later on.

I prefer pre-build them into .js when publishing.

Qiaosen Huang
  • 1,093
  • 1
  • 10
  • 25
  • My worry is also that individual files in the library export their functions so that other files can use them, and it seems then that users of the library can access them. I'd want that only functions and types exported by the `index.ts` are exported by the library but looking at the doc generated by `typedoc` it seems it's not what's happening. Did you do anything about that? Is your library's source online btw? – Emmanuel Touzery Dec 29 '16 at 08:26
  • 1
    https://github.com/t2ee/vader. Do not worry about typedoc. It is the same as NodeJs ( or say commonJs module system ), users have all the definitions your project generated. But they only have access to what was exported. – Qiaosen Huang Dec 29 '16 at 08:42
  • yes, but I do export them. To give an example. `parseView` is for internal use only https://github.com/emmanueltouzery/ng-typeview/blob/479f86450d6a7e6c824bcad85fa18771401e168d/src/view-parser.ts#L176 -- but I do export it from `view-parser.ts` so that https://github.com/emmanueltouzery/ng-typeview/blob/479f86450d6a7e6c824bcad85fa18771401e168d/src/ng-typeview.ts#L7 `ng-typeview` can use it. However I can create an `index.ts` NOT reexporting `parseView`. But since `typedoc` ignores that and documents `parseView` anyway it makes me think that this does not work like that. – Emmanuel Touzery Dec 29 '16 at 08:52
  • assuming users really can't use them though, then I'd probably have to open a bug against `typeview` because users of my library should not see any docs for `parseView` and others. I'd only confuse them. This is not external API... – Emmanuel Touzery Dec 29 '16 at 08:53
  • As long as it's accessible in `index.ts`, you are fine. https://github.com/TypeStrong/typedoc/issues/170, check this for ignoring modules – Qiaosen Huang Dec 29 '16 at 08:56
  • @EmmanuelTouzery, if you use modules to export your project, check https://github.com/excaliburjs/Excalibur for an example – Qiaosen Huang Dec 29 '16 at 08:59
  • Discovered the `@hidden` typeview annotation which allows me to hide symbols. I did open them a bug though, to make sure. https://github.com/TypeStrong/typedoc/issues/368 – Emmanuel Touzery Dec 29 '16 at 09:39
1

I'd suggest you to take a look at TypeScript Library Starter. It configures out of the box:

  • Package.json configuration
  • Universal module bundles
  • Source Maps
  • Typings (.d.ts)
  • Docs using TypeDoc
  • Tests and coverage
Alex JM
  • 1,084
  • 2
  • 11
  • 32