Shipping TypeScript to npm

How we shipped @azure/cosmos in a way that everyone can happily consume it from npm. Presented at TypeScript NYC meetup on Feb 26th 2019

Transcript

1. Shipping TypeScript to npm
2. Steve Faulkner @southpolesteve
7. Why Cosmos DB?
8. Read/Write JSON Massive scale+perf No schema SQL API Everything indexed by default! Tune-able consistency JavaScript stored procedures
9. npm install @azure/cosmos https://portal.azure.com
10. Can we write TypeScript, ship to npm, and make everyone happy?
11. Who uses npm?
12. Node Users
13. commonjs esm
14. Browser Users
15. commonjs esm amd globals
16. TypeScript Users
17. types
18. Step 1: tsconfig module: commonjs outDir: ./dist types: ./dist/index.d.ts
19. Consumer Report esm amd global webpack
20. Step 2: tsconfig module: umd
21. Universal Module Definition
22. Consumer Report global
24. “UMD”
25. Step 3 rollup.js
26. typescript(esm) -> cjs rollup(cjs) -> umd
27. Consumer Report esm webpack typescript
28. Step 4 typescript(esm) -> esm rollup(esm) -> umd
29. Consumer Report esm webpack typescript
30. Step 4 @microsoft/api-extractor
31. Rollup for .d.ts
32. Consumer Report
33. If only that were the end….
34. Now you want actually write code!
35. Part 2: The ways you will break typescript users
36. 1: “lib”
37. lib: ["esnext"]
38. /// <reference lib="esnext" />
39. lib: []
40. lib
41. 2: ES modules
42. import * as assert from 'assert' assert()
43. "esModuleInterop": true
44. import assert from 'assert' assert()
45. 3: Leaking Types
46. import { Agent } from “http” export interface ClientOptions { agent?: Agent; }
47. 1. npm i @types/node 2. Mirror types
48. interface Agent { maxFreeSockets: number; requests: any; } interface ClientOptions { agent?: Agent; }
49. // In tests! import { Agent } from “http” let opts : ClientOptions = { agent: new Agent() }
50. 4: Enums
51. enum Color { Red, Green } const green = Color.Green const red: Color = “Red”
52. export const Color = { Red: "Red", Green: "Green" };
53. export const Color = { Red: "Red" as "Red", Green: "Green" as "Green" };
54. export const Color = { Red: "Red" as “Red", Green: "Green" as "Green" }; const green: Color = Color.Green const red: Color = “Red”
55. 5: Changing TS versions
56. 3.0 -> 3.1
57. /// <reference lib="" />
58. Minor versions of TS will introduce breaking type syntax
59. Have a typescript consumer test
60. let versions = [ "3.0", "3.1", “latest" ]; exec(`npx -p typescript@${version} tsc`);
61. Recap
62. typescript(esm) -> esm rollup(esm) -> umd apiExtractor(index.d.ts) Don’t use “lib” esModuleInterop: true Mirror @types interfaces Don’t use enums Have a TS consumer tests
63. https://github.com/ Azure/azure-sdk
64. Disclaimers: I don’t work on TypeScript Not official guidance This info is already stale
65. Questions? @southpolesteve