How I Use Angular 2 with Webpack: Directory Structure

Reading time: 2 minutes

A disclaimer: I’m not claiming to be an expert here and I’m open to any corrections or input from everyone; this is just what’s worked for me so far. Please enjoy!

The Angular 2 tutorials present SystemJS as the module-loading…uh…system of choice. I prefer Webpack to do my module-loading. I like that it focuses on a build-time versus run-time, but I’m not going to go into the merits of each. In this series, I just wanted to provide an insight of how Webpack can be used to setup an Angular project.

Here’s the run-down of what I’ll be talking about in the series:

  1. Directory Structure
  2. Node Modules & NPM Configuration
  3. Typings
  4. Code Linting
  5. TypeScript Configuration
  6. Karma Configuration
  7. Webpack Configuration
  8. Sample Application

In this post, we’ll just look at how I setup the structure of the project.

Project Structure

There are no less that 6 million (statistics may vary) ways to structure a project. The way that I structure an Angular 2 project is as follows:

You may notice I try to keep similar files organized in directories together as best I can. The code is bundled in the following “categories”:

  • Source Code
    • Application Code
    • Test Code
  • Typings Definitions
  • Webpack Configuration

Any files left in the root directory are either required to be there or not worth the effort to keep in a directory.

Root-Directory Files

There are four files in the root directory. Again, these are here out of necessity (mostly because the application that uses them, requires the file to be in a specific location):

  • package.json: the file that manages the dependencies we’ll install later via NPM and scripts needed to compile the source code.
  • tsconfig.json: the TypeScript configuration file. This sets a bunch of options so that TypeScript can compile .ts files into JavaScript.
  • tslint.json: similar to a JSHint or ESLint configuration file, this lays out the configuration of code-styling rules to help avoid any coding errors in TypeScript files.
  • typings.json: similar to the package.json file but only manages the TypeScript definition files for the project (see below for more explanation).

Source Code Organization

I like to keep all of the code organized under the src directory. Where it seems a lot of people differ from my opinion is that they put all the application & test code in the same folder, so a component would have the application code side-by-side with its test code. I find this to be cluttered, so under my src directory the code is split between the app (application code) and test (test code) directories. There’s really no “right” answer here, just different opinions.

Application Directory

The app directory is fairly simple at the start:

  • scripts: where all my TyepScript files will go
  • main.scss: I use SASS to manage my CSS styles and this is the global styling sheet
  • index.html: pretty obvious, but this is the main HTML file

Test Directory

Under the test directory is all the code for testing:

  • fixtures: where I’ll keep complex data for tests
  • karma: where my Karma configuration files are kept
  • specs: where I keep the actual test scripts with a structure mirroring src/app/scripts

Typings Definitions

Typings is the manager of TypeScript definition files (it replaces an earlier manager called TSD). TypeScript definition files make it so TypeScript understands the APIs of external libraries. All files for TypeScript definitions have the extension .d.ts and some libraries (like Angular 2) have started providing definition files as part of their distributions.

The contents of this directory will be handled by the Typings application (which we’ll see in the next post).

Webpack Configuration

By default, Webpack looks for the configuration file webpack.config.js in the root directory. But the Webpack configuration can be slightly different given the stage of development you’re in. For example, there could be a for development, a webpack.test.js for testing, and a webpack.dist.js for building the application for distribution. So I keep those configurations in a webpack directory and reference them explicitly instead when they’re needed.

And That’s It!

That’s the basic structure I use for my applications. In the next post I’ll actually pull in the dependencies needed and write the first configuration file. In the final post, we’ll write a small, sample application to see it all in action.

Leave a Comment

Your email address will not be published. Required fields are marked *