This guide will teach you how to wire up TypeScript with React and webpack.
\nIf you’re starting a brand new project, take a look at the React Quick Start guide first.
\nOtherwise, we assume that you’re already using Node.js with npm.
\nLet’s start out with a new directory.\nWe’ll name it proj for now, but you can change it to whatever you want.
\nshellmkdir proj\ncd proj
To start, we’re going to structure our project in the following way:
\nproj/\n├─ dist/\n└─ src/\n └─ components/\nTypeScript files will start out in your src folder, run through the TypeScript compiler, then webpack, and end up in a main.js file in dist.\nAny components that we write will go in the src/components folder.
Let’s scaffold this out:
\n\nshellmkdir src\ncd src\nmkdir components\ncd ..
Webpack will eventually generate the dist directory for us.
Now we’ll turn this folder into an npm package.
\n\nshellnpm init -y
This creates a package.json file with default values.
First ensure Webpack is installed.
\n\nshellnpm install --save-dev webpack webpack-cli
Webpack is a tool that will bundle your code and optionally all of its dependencies into a single .js file.
Let’s now add React and React-DOM, along with their declaration files, as dependencies to your package.json file:
\nshellnpm install --save react react-dom\nnpm install --save-dev @types/react @types/react-dom
That @types/ prefix means that we also want to get the declaration files for React and React-DOM.\nUsually when you import a path like \"react\", it will look inside of the react package itself;\nhowever, not all packages include declaration files, so TypeScript also looks in the @types/react package as well.\nYou’ll see that we won’t even have to think about this later on.
Next, we’ll add development-time dependencies on the ts-loader and source-map-loader.
\n\nshellnpm install --save-dev typescript ts-loader source-map-loader
Both of these dependencies will let TypeScript and webpack play well together.\nts-loader helps Webpack compile your TypeScript code using the TypeScript’s standard configuration file named tsconfig.json.\nsource-map-loader uses any sourcemap outputs from TypeScript to inform webpack when generating its own sourcemaps.\nThis will allow you to debug your final output file as if you were debugging your original TypeScript source code.
Please note that ts-loader is not the only loader for typescript.\nYou could instead use awesome-typescript-loader.
\nRead about the differences between them here.
\nNotice that we installed TypeScript as a development dependency.\nWe could also have linked TypeScript to a global copy with npm link typescript, but this is a less common scenario.
You’ll want to bring your TypeScript files together - both the code you’ll be writing as well as any necessary declaration files.
\nTo do this, you’ll need to create a tsconfig.json which contains a list of your input files as well as all your compilation settings.\nSimply create a new file in your project root named tsconfig.json and fill it with the following contents:
\njson{\n \"compilerOptions\": {\n \"outDir\": \"./dist/\",\n \"sourceMap\": true,\n \"noImplicitAny\": true,\n \"module\": \"commonjs\",\n \"target\": \"es6\",\n \"jsx\": \"react\"\n }\n}
You can learn more about tsconfig.json files here.
Let’s write our first TypeScript file using React.\nFirst, create a file named Hello.tsx in src/components and write the following:
\ntsimport * as React from \"react\";\n\nexport interface HelloProps { compiler: string; framework: string; }\n\nexport const Hello = (props: HelloProps) => <h1>Hello from {props.compiler} and {props.framework}!</h1>;
Note that while this example uses function components, we could also make our example a little classier as well.
\n\ntsimport * as React from \"react\";\n\nexport interface HelloProps { compiler: string; framework: string; }\n\n// 'HelloProps' describes the shape of props.\n// State is never set so we use the '{}' type.\nexport class Hello extends React.Component<HelloProps, {}> {\n render() {\n return <h1>Hello from {this.props.compiler} and {this.props.framework}!</h1>;\n }\n}
Next, let’s create an index.tsx in src with the following source:
\ntsimport * as React from \"react\";\nimport * as ReactDOM from \"react-dom\";\n\nimport { Hello } from \"./components/Hello\";\n\nReactDOM.render(\n <Hello compiler=\"TypeScript\" framework=\"React\" />,\n document.getElementById(\"example\")\n);
We just imported our Hello component into index.tsx.\nNotice that unlike with \"react\" or \"react-dom\", we used a relative path to Hello.tsx - this is important.\nIf we hadn’t, TypeScript would’ve instead tried looking in our node_modules folder.
We’ll also need a page to display our Hello component.\nCreate a file at the root of proj named index.html with the following contents:
\nhtml<!DOCTYPE html>\n<html>\n <head>\n <meta charset=\"UTF-8\" />\n <title>Hello React!</title>\n </head>\n <body>\n <div id=\"example\"></div>\n\n <!-- Dependencies -->\n <script src=\"./node_modules/react/umd/react.development.js\"></script>\n <script src=\"./node_modules/react-dom/umd/react-dom.development.js\"></script>\n\n <!-- Main -->\n <script src=\"./dist/main.js\"></script>\n </body>\n</html>
Notice that we’re including files from within node_modules.\nReact and React-DOM’s npm packages include standalone .js files that you can include in a web page, and we’re referencing them directly to get things moving faster.\nFeel free to copy these files to another directory, or alternatively, host them on a content delivery network (CDN).\nFacebook makes CDN-hosted versions of React available, and you can read more about that here.
Create a webpack.config.js file at the root of the project directory.
\njsmodule.exports = {\n mode: \"production\",\n\n // Enable sourcemaps for debugging webpack's output.\n devtool: \"source-map\",\n\n resolve: {\n // Add '.ts' and '.tsx' as resolvable extensions.\n extensions: [\".ts\", \".tsx\"]\n },\n\n module: {\n rules: [\n {\n test: /\\.ts(x?)$/,\n exclude: /node_modules/,\n use: [\n {\n loader: \"ts-loader\"\n }\n ]\n },\n // All output '.js' files will have any sourcemaps re-processed by 'source-map-loader'.\n {\n enforce: \"pre\",\n test: /\\.js$/,\n loader: \"source-map-loader\"\n }\n ]\n },\n\n // When importing a module whose path matches one of the following, just\n // assume a corresponding global variable exists and use that instead.\n // This is important because it allows us to avoid bundling all of our\n // dependencies, which allows browsers to cache those libraries between builds.\n externals: {\n \"react\": \"React\",\n \"react-dom\": \"ReactDOM\"\n }\n};
You might be wondering about that externals field.\nWe want to avoid bundling all of React into the same file, since this increases compilation time and browsers will typically be able to cache a library if it doesn’t change.
Ideally, we’d just import the React module from within the browser, but most browsers still don’t quite support modules yet.\nInstead libraries have traditionally made themselves available using a single global variable like jQuery or _.\nThis is called the “namespace pattern”, and webpack allows us to continue leveraging libraries written that way.\nWith our entry for \"react\": \"React\", webpack will work its magic to make any import of \"react\" load from the React variable.
You can learn more about configuring webpack here.
\nJust run:
\n\nshellnpx webpack
Now open up index.html in your favorite browser and everything should be ready to use!\nYou should see a page that says “Hello from TypeScript and React!”