You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+7-3
Original file line number
Diff line number
Diff line change
@@ -1,10 +1,14 @@
1
1
# Example TypeScript Package ready to be published on npm for 2021
2
2
3
-
This is an example TypeScript Package ready to be published on npm. It has been set up with automated tests and package publishing workflow using GitHub Actions CI/CD. It is made primarily for GitHub<a href="https://github.com/" title="Github"><img src="https://github.com/tomchen/stack-icons/raw/master/logos/github-icon.svg" alt="Github" width="21px" height="21px"></a> + VS Code<a href="https://code.visualstudio.com/" title="Visual Studio Code"><img src="https://github.com/tomchen/stack-icons/raw/master/logos/visual-studio-code.svg" alt="Visual Studio Code" width="21px" height="21px"></a> (Windows<a href="https://www.microsoft.com/windows" title="Windows"><img src="https://github.com/tomchen/stack-icons/raw/master/logos/microsoft-windows.svg" alt="Windows" width="21px" height="21px"></a> / Mac<a href="https://www.apple.com/macos/" title="Mac OS"><img src="https://github.com/tomchen/stack-icons/raw/master/logos/macOS.svg" alt="Mac OS" width="21px" height="21px"></a> / Linux<a href="https://www.linuxfoundation.org/" title="Linux"><img src="https://github.com/tomchen/stack-icons/raw/master/logos/linux-tux.svg" alt="Linux" width="21px" height="21px"></a>) users who are about to write and publish their first TypeScript npm package. This package could serve as a starter / boilerplate / demo for them.
3
+
This is an example TypeScript Package ready to be published on npm. It has been set up with automated tests and package publishing workflow using GitHub Actions CI/CD. It is made primarily for GitHub + VS Code (Windows / Mac / Linux) users who are about to write and publish their first TypeScript npm package. This package could serve as a starter / boilerplate / demo for them.
It uses npm<a href="https://www.npmjs.com/" title="npm"><img src="https://github.com/tomchen/stack-icons/raw/master/logos/npm.svg" alt="npm" width="21px" height="21px"></a>, TypeScript compiler<a href="https://www.typescriptlang.org/" title="Typescript"><img src="https://github.com/tomchen/stack-icons/raw/master/logos/typescript-icon.svg" alt="Typescript" width="21px" height="21px"></a>, Jest<a href="https://jestjs.io/" title="Jest"><img src="https://github.com/tomchen/stack-icons/raw/master/logos/jest.svg" alt="Jest" width="21px" height="21px"></a>, webpack<a href="https://webpack.js.org/" title="webpack"><img src="https://github.com/tomchen/stack-icons/raw/master/logos/webpack.svg" alt="webpack" width="21px" height="21px"></a>, ESLint<a href="https://eslint.org/" title="ESLint"><img src="https://github.com/tomchen/stack-icons/raw/master/logos/eslint.svg" alt="ESLint" width="21px" height="21px"></a>, Prettier<a href="https://prettier.io/" title="Prettier"><img src="https://github.com/tomchen/stack-icons/raw/master/logos/prettier.svg" alt="Prettier" width="21px" height="21px"></a>. The production files include CommonJS, ES Modules, UMD version and TypeScript declaration files.
7
+
It uses npm, TypeScript compiler, Jest, webpack, ESLint, Prettier. The production files include CommonJS, ES Modules, UMD version and TypeScript declaration files.
Congratulations choosing TypeScript as one of your first languages - you're already making good decisions.
45
+
46
+
You've probably already heard that TypeScript is a "flavor" or "variant" of JavaScript.
47
+
The relationship between TypeScript and JavaScript is rather unique among modern programming languages, so learning more about this relationship will help you understand how TypeScript adds to JavaScript.
48
+
49
+
## What is JavaScript? A Brief History
50
+
51
+
JavaScript started as a simple scripting language available in browers.
52
+
When the language was first invented, writing more than a few dozen lines of JavaScript (JS) in a webpage would have been somewhat unusual.
53
+
Over time, though, JS became more common and web developers used more and more JS in their webpages to create interactive experiences.
54
+
Early web browsers executed JS very slowly and this sometimes led to laggy, unresponsive pages.
55
+
56
+
Web browser developers saw the increased use of JS and started to optimize their browsers to run JS more quickly.
57
+
Web developers responded by using JS even more to increase the interactivity of their pages.
58
+
On modern websites, you might be running tens or even hundreds of thousands of lines of JS code.
59
+
The web, which started as a simple network of static pages, has evolved into a platform for rich *applications* of all kinds.
60
+
61
+
Lately, JS has also become a popular choice for non-browser scenarios, such as running servers using node.js.
62
+
The "run anywhere" nature of JS makes it an attractive choice for cross-platform development.
63
+
Many developers these days use *only* JavaScript to program their entire stack!
64
+
65
+
The net result is that a very simple language designed to provide basic webpage interactivity is now being used to write applications with millions of lines of code.
66
+
67
+
JavaScript's humble beginnings are still visible in its many *quirks* - oddities or surprises that are not typical for other programming languages.
68
+
For example, JavaScript's equality operator `==` *coerces* its arguments, leading to unexpected behavior:
69
+
```js
70
+
if ("" == 0) {
71
+
// It is! But why??
72
+
}
73
+
```
74
+
75
+
JavaScript also allows accessing properties which aren't present:
76
+
```js
77
+
const obj = { width: 10, height: 15 };
78
+
// Why is this NaN? Spelling is hard!
79
+
const area = obj.width * obj.heigth;
80
+
```
81
+
82
+
Other programming languages would usually cause these programs to either fail to start at all, or terminate the program mid-execution, if these sorts of errors occur.
83
+
When writing small programs, these quirks are annoying but manageable; when writing applications with hundreds or thousands of lines of code, these constant surprises make development slow and frustrating.
84
+
85
+
## TypeScript: A Static Type Checker
86
+
87
+
We said earlier that other programming languages wouldn't allow those buggy programs to run at all.
88
+
Detecting errors in code without running it is referred to as *static* checking.
89
+
Determining what's an error and what's not based on the kinds of values being operated on is known as *type* checking.
90
+
91
+
Because TypeScript checks a program for errors before it's run, and does so based on the *kinds of values*, it's a *static type checker*.
92
+
For example, the snippet from earlier has an error because of the *type* of `obj`.
93
+
Here's the error TypeScript found:
94
+
95
+
```ts
96
+
const obj = { width: 10, height: 15 };
97
+
const area = obj.width * obj.heigth;
98
+
```
99
+
100
+
### A Typed Superset of JavaScript
101
+
102
+
How does TypeScript relate to JavaScript, though?
103
+
104
+
#### Syntax
105
+
106
+
TypeScript is a programming language where all JavaScript syntax is legal.
107
+
Syntax refers to the way we arrange characters to form a program.
108
+
For example, this code has a *syntax* error because it's missing a `)`:
109
+
110
+
```js
111
+
let a = (4
112
+
```
113
+
114
+
TypeScript doesn't consider any JavaScript code to be an error because of its syntax.
115
+
This means you can take any working JavaScript code and put it in a TypeScript file without worrying about exactly how it's written.
116
+
117
+
#### Types
118
+
119
+
However, TypeScript is a *typed* superset, meaning that it adds rules about how different kinds of values can be used.
120
+
The earlier error about `obj.heigth` was not an error about the *syntax* of the program, but instead an error about using a kind of value (a *type*) in an incorrect way.
121
+
122
+
As another example, this is JavaScript code you can run in a browser that *will* print a value:
123
+
```js
124
+
console.log(4 / []);
125
+
```
126
+
127
+
This syntactically-legal program prints `NaN`.
128
+
TypeScript, though, considers division of number by an array to be a nonsensical operation, and will issue an error:
129
+
130
+
```ts
131
+
console.log(4 / []);
132
+
```
133
+
134
+
It's entirely possible you really did intend to divide a number by an array, perhaps just to see what would happen.
135
+
The vast majority of the time, though, this code is a mistake on the programmer's part.
136
+
TypeScript's type system rules are designed to allow correct programs through while still catching as many common errors as possible.
137
+
Later, we'll learn about settings you can use to configure how strictly TypeScript checks your code.
138
+
139
+
If you move some code from a JavaScript file to a TypeScript file, you might see *type errors* depending on how the code is written.
140
+
These may be legitimate problems with the code, or TypeScript being overly conservative.
141
+
Throughout this guide we'll demonstrate how to add various TypeScript syntax to make these errors go away.
142
+
143
+
#### Runtime Behavior
144
+
145
+
TypeScript is also a programming language that preserves the *runtime behavior* of JavaScript.
146
+
For example, dividing by zero in JavaScript produces `Infinity` instead of throwing a runtime exception.
147
+
TypeScript **never** changes the runtime behavior of JavaScript code.
148
+
149
+
This means code you move from JavaScript to TypeScript is **guaranteed** to do the same thing, even if TypeScript thinks that code has type errors.
150
+
151
+
Keeping the same runtime behavior as JavaScript is a foundational promise of TypeScript because it means you can easily transition between the two languages without worrying about subtle differences that might make your program stop working.
152
+
153
+
#### Erased Types
154
+
155
+
TypeScript's type system is *erased*, meaning that once your code is compiled, there is no persisted type information in the resulting JavaScript code.
156
+
157
+
TypeScript also never changes the behavior of your program based on the types it inferred.
158
+
While you might see more or fewer type errors, the type system itself has no bearing on how your program works once it's running.
159
+
160
+
Finally, TypeScript doesn't provide any additional runtime libraries.
161
+
Your programs will use the same standard library (or external libraries) as JavaScript programs, so there's no additional TypeScript-specific framework to learn.
162
+
163
+
## Learning JavaScript and TypeScript
164
+
165
+
We frequently see the question "Should I learn JavaScript, or TypeScript instead?".
166
+
167
+
The answer is that you can't do one without doing the other!
168
+
Because TypeScript shares syntax and runtime behavior with JavaScript, anything you learn about JavaScript is helping you learn TypeScript at the same time.
169
+
170
+
There are many, many resources available for programmers learning JavaScript, and you shouldn't ignore these resources if you're writing TypeScript.
171
+
For example, there about 20 times more StackOverflow questions tagged `javascript` than `typescript`, but *all* of the `javascript` questions also apply to TypeScript.
172
+
173
+
If you find yourself searching for something like "how to sort a list in TypeScript", remember, **TypeScript is JavaScript's runtime with a build-time type system**.
174
+
The way you sort a list in TypeScript is the same way you sort a list in JavaScript.
175
+
If you find a resource that does use TypeScript, that's great too, but don't limit yourself to thinking you need TypeScript-specific answers for everyday questions about how to accomplish runtime tasks.
0 commit comments