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:
- Directory Structure
- Node Modules & NPM Configuration
- Code Linting
- TypeScript Configuration
- Karma Configuration
- Webpack Configuration
- Sample Application
In this post, we’ll just look at how I setup the structure of the project.
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.
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
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.jsonfile 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.
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 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
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).
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
webpack.dev.js 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.