Files and Folders

When you set up an Angular 2 application using Angular CLI, it populates a folder for your development work. This folder includes the node_modules (libraries your application might need), the source code to your application, and some testing tools. In this chapter, we explore these folders and files.

Folder structure

After project creation, Angular 2 applications will have a root folder (for configuration files) and several other common folders:

• src: The main folder for your application’s source code.
• node_modules: The folder where libraries are stored.
• e2e: The end-to-end testing folder.

Here is a look at the structure within Visual Studio Code.

Figure 6: Folder Structure

GitHub files

The default application contains a couple files needed by Git and GitHub. These are the .gitignore and README.md files. If you are interested in learning more about GitHub, you can download my book GitHub Succinctly from the Syncfusion website.

.gitignore

The .gitignore file is the standard file instructing GitHub and Git which files in a folder should be excluded (or ignored) from Git version control. You can specify files or folders not to check into the repository, such as:

• /dist: Ignore files in the distribution folder.
• .map: Don’t commit any map files.
• /node_modules: Don’t commit the various Angular or other libraries.

Lines beginning with a # are comment lines.

README.md

GitHub projects contain a README.md file that is displayed as part of the GitHub listing. The Angular CLI will include a readme file for you when creating a new project.

Figure 7: Sample GitHub Readme

If you are not using GitHub, you can ignore these files, but having them generated for you is a nice time-saver.

.editorconfig

This file allows you to provide configuration settings for your editor. You can set various properties, such as indent_style (tab or space) and indent_size (number). Visual Studio Code doesn’t natively support .editorconfig, but you can install a plugin that supports it by pressing Ctrl+Shift+P and entering the following command.

Code Listing 19

Tip: If you try to create a file beginning with a period, Windows will view it as a file extension and ask for a file name. However, if you put a period at the end as well, Windows will create the file.

angular-cli.json

This file allows you to configure the behavior of the Angular CLI tool. There are various sections, such as project, apps, and defaults. The apps group contains most of the options you might need to customize. Here are a few of the settings you might use:

• apps/root: Folder where the root application is, using src.
• apps/outDir: Folder to hold the distribution, typically dist.
• apps/assets: Files and folders that should be included with distribution.
• apps/styles: Collection of style sheets to bundle into the application.
• apps/scripts: Collection of JavaScript files to bundle.

package.json

This file tells NPM which dependencies are needed for your application. While you might not need them all, there is no harm in adding more packages than you use. Your client application will only get the packages you actually use in your code, not the entire list from this file. Since this is a JSON file, the elements described here will be between { } in the actual file.

Package information

This section contains information about the package, such as its name and version.

Code Listing 20

The name attribute is required, and must be lowercase. The version, description, and author attributes are optional, but should be provided in case another developer wants to find out information about your application.

Scripts

The scripts section is used to provide commands to the NPM command-line application.

Code Listing 21

When you run the NPM start command to launch your application, you are actually running the Angular 2 serve command, which trans-compiles the TypeScript files and opens the server on the local host. You can add additional scripts, perhaps to compress your JavaScript files, for example.

License

The purpose of the package.json file is to provide information about your application, and if the package is open source, you can specify the license on the package, such as MIT. You can also set the license to UNLICENSED and add the private attribute (set to true). However, once you’ve completed your package, you can publish it to the Node repository for others if you would like. For now, we will keep our project private with the following attributes.

Code Listing 22

Note: There are a number of additional attributes available for describing the package and adding keywords to make it available as open source to other developers. If you decide to make your package available to the public, explore attributes like repository (location where source is), keywords (to make searching for it easier), and bugs (email address where to report any bugs).

Dependencies

The dependencies section lists all the modules that your package relies on, and will be automatically added when someone installs your package. The list of dependencies you might need for an Angular 2 application is shown in the following code listing.

Code Listing 23

When we run the install command, these dependencies will be added to your application folder from the Node repository. You can use the list in Code Listing 23 as a good starting point, but you might start adjusting this as you work more with Angular 2 applications. Comments are actually not supported in a JSON file; the comments in this example are just for indicating what the various modules are for. The configuration files available on the Syncfusion Bitbucket page do not have comments.

Note: At the time of this writing, Angular 2 was on version 2.2.3. You might need to update your dependencies as future versions of Angular are released.

devDependencies

This section lists the dependencies that are only needed for development and testing your application. When doing a production release, these dependencies will not be added.

Code Listing 24

The package.json file interacts with NPM to install dependencies. Your version numbers might be different from the examples in Code Listing 24, but by keeping this configuration file with the project, you can ensure current production projects stay stable on the same versions, while possibly exploring updated versions for later applications.

tsLint.json

This configuration file lets you set up the options for the codelyzer lint checker. A lint checker is a nice additional tool (installed as part of Angular CLI), but sometimes your coding style could cause unnecessary warnings. These warnings can clutter your lint checking, and make it hard to see the beneficial warnings. By customizing the file, you can adapt the lint checker to work with your coding style.

For example, the any type in TypeScript is allowed, but somewhat defeats the purpose of a strongly typed language. You can control whether to report usage of any with the following entry in the configuration file.

Code Listing 25

Tip: Lint checkers are handy tools for reducing the likelihood of certain errors that will compile, but they may cause problems at run-time. Every rule checked generally has a good reason for it, so be sure to decide whether the rule is actually a nuisance or if you should rethink your coding style. The first time that code runs, it will download the Hadoop Succinctly Docker image from the public repository. That will take a while, but then Docker caches the image locally, which means the next time you run the command, the container will start in only a few seconds.

src folder

The src folder contains the configuration file for the TypeScript compiler and the type specifications.

tsConfig.json

The tsConfig.json file contains the compiler options for TypeScript. It allows us to specify how we want the .ts files to be transpiled into JavaScript files. The options we use for our default are shown in the following code listing.

Code Listing 26

You do not have to have a tsConfig.json file, but it is included to get the exact behavior we want, including when we want ES5 (ECMAScript 5) rather than the default ECMAScript 3. We’ve also chosen to keep comments in the trans-compiled JavaScript code. You can read Steve Fenton’s book on TypeScript if you want more details on the compiler options.

typings.json

Some JavaScript libraries (such as jQuery) add features and syntax to the JavaScript environment that the TypeScript compiler doesn’t know how to handle. When the compiler doesn’t know how to handle the syntax, it throws an error.

Library developers might create their own type declaration files (- d.ts extension). These would provide the compiler with information about features in the libraries. The typings.json file tells the compiler where to find the definition files for libraries we might use. The following lines of code provide typing location information for three features we might need during our application development.

Code Listing 27

These lines indicate that these particular libraries will be used, so the NPM program should find them and install them as part of building this application. However, while these libraries are not needed for Hello World (although useful for other applications), you will get a warning message about them).

Figure 8: TypeScript Warning Message

To fix the warning message, you will need to update the library using the typings install feature. The syntax is as follows.

Code Listing 28

This command runs the typings application and passes everything after the double dash to the typings program, so it becomes:

Code Listing 29

You will notice that the typings d.ts file has been updated (look in typings\globals\jasmine), and the typings.json file has also been updated with the latest version number.

Code Listing 30

You can also run this command.

Code Listing 31

This will show you a list of all the typings files (d.ts) that have been installed for the application.

Note: You should not need to edit the typings.json file manually, but rather use the typings tool to update the dependencies and version numbers.

Summary

There are many configuration files with the project, which provide great deal of flexibility in how you develop your Angular 2 applications. The most common ones you’ll need in development are the package.json (to get libraries and new versions) and angular-cli.json (for controlling the code generation and execution in the application) files.