|
1 | | -vscode-typescript-boilerplate |
2 | | -========================= |
3 | | - |
4 | | -This project provides a skeleton structure and IDE settings files to help with TypeScript development in [Visual Studio Code][vscode] (as of build 0.9.1). The project builds all TypeScript (`.ts`) files into a `build` directory in the root. |
5 | | - |
6 | | -## Project Structure |
7 | | -The project currently provides the following features: |
8 | | -* TypeScript compilation with Code's build command, or via `npm run build`, providing source maps |
9 | | -* Mocha test structure, which can be run with Code or `npm test`, also with source maps |
10 | | -* Error detection and navigation within Code for both build and test problems (see [Code Tasks](https://code.visualstudio.com/Docs/editor/tasks)) |
11 | | -* Debug settings (_currently a bug is preventing this from being reliable_) |
12 | | -* Type definitions provided by [`typings`][typings] |
13 | | -* Custom type definitions ready for your own declarations |
14 | | - |
15 | | -### Project Structure |
16 | | -``` |
17 | | -.vscode/ |
18 | | - launch.json # Defines launch tasks for debugging etc. |
19 | | - tasks.json # Defines tasks available e.g. build & test |
20 | | -
|
21 | | -build/ # The output directory of JavaScript files |
22 | | - # when built from TypeScript |
23 | | - |
24 | | -src/ # The root of all TypeScript source code |
25 | | - app/ |
26 | | - app.ts # The main entry point for the project. |
27 | | - mymodule.ts # A sample module |
28 | | - |
29 | | - test/ |
30 | | - app.test.ts # A sample test |
31 | | - app.test.ts # A sample module test with sinon spies |
32 | | - |
33 | | - typings/ # Typings downloaded using the typings command |
34 | | - |
35 | | - custom.d.ts # An example of custom ambient typings |
36 | | - |
37 | | - tsconfig.json # TypeScript compilation settings |
38 | | - typings.json # TypeScript package definition file for typings |
39 | | - |
40 | | -package.json |
41 | | -README.md |
42 | | -``` |
43 | | - |
44 | | -## Getting Started |
45 | | -This repository is ready for you to clone and start building your code around it. Simply follow the guide below. |
46 | | - |
47 | | -### Prerequisites |
48 | | -1. Clone, fork, or [download](//github.com/Codesleuth/vscode-typescript-boilerplate/releases) the project. |
49 | | -2. You need Node.js. [Go install it][nodejsdownload] |
50 | | -3. Ensure the required dependencies have been installed: |
51 | | - ```bash |
52 | | - $ npm install |
53 | | - ``` |
54 | | - |
55 | | -4. You will need [`typings`][typings] to allow the TypeScript to compile without errors. It's recommended to install this globally: |
56 | | - ```bash |
57 | | - $ npm install typings -g |
58 | | - ``` |
59 | | -
|
60 | | -5. Change to the `src` directory and run `typings install` to fetch the required module type definitions defined in `typings.json`: |
61 | | - ```bash |
62 | | - $ cd src |
63 | | - |
64 | | - # if installed globally (recommended) |
65 | | - $ typings install |
66 | | -
|
67 | | - # otherwise |
68 | | - $ ../node_modules/.bin/typings install |
69 | | - ``` |
70 | | -
|
71 | | -### Building |
72 | | -1. Open VSCode, hit <kbd>CTRL</kbd>/<kbd>Cmd</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd>, type `open folder` and select the root of this repository |
73 | | -2. Build with one of the following shortcuts: |
74 | | - * Press <kbd>CTRL</kbd>/<kbd>Cmd</kbd>+<kbd>Shift</kbd>+<kbd>B</kbd> to build, which is declared in the `.vscode/tasks.json` file with the `isBuildCommand` marker |
75 | | - * Press <kbd>CTRL</kbd>/<kbd>Cmd</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> and select the `Tasks: Run Build Task` option |
76 | | - * Press <kbd>CTRL</kbd>/<kbd>Cmd</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd>, delete the `>` and type `task build` |
77 | | -3. If there were no errors, you should see a new directory, `build`, in the root with the following content: |
78 | | -``` |
79 | | -build/ |
80 | | - app/ |
81 | | - app.js |
82 | | - app.js.map |
83 | | - mymodule.js |
84 | | - mymodule.js.map |
85 | | - test/ |
86 | | - app.test.js |
87 | | - app.test.js.map |
88 | | - mymodule.test.js |
89 | | - mymodule.test.js.map |
90 | | -``` |
91 | | -
|
92 | | -### Error Navigation |
93 | | -After building or testing, errors are captured (defined in the `.vscode/tasks.json` file) and can be viewed with <kbd>CTRL</kbd>/<kbd>Command</kbd>+<kbd>Shift</kbd>+<kbd>M</kbd>. |
94 | | -
|
95 | | -Your `.ts` files have been compiled to `.js` files within the `build` directory, and each should have a `.js.map` _sourcemap_ file alongside it to allow stack traces to correctly report the line in the original file. See [this StackOverflow article][sourcemapquestion] for an overview of what a sourcemap is. |
96 | | -
|
97 | | -### Testing |
98 | | -There are sample tests located in the `test` folder. You can run them by hitting <kbd>CTRL</kbd>/<kbd>Command</kbd>+<kbd>Shift</kbd>+<kbd>T</kbd> (or use the `Tasks` menu and run `Tasks: Run Test Task`) |
99 | | -
|
100 | | -### Running and Debugging |
101 | | -To run the project in debug mode, simply hit <kbd>F5</kbd>! Place breakpoints in your TypeScript code and view them in the debugger (<kbd>CTRL</kbd>+<kbd>Shift</kbd>+<kbd>D</kbd> or <kbd>Cmd</kbd>+<kbd>Shift</kbd>+<kbd>D</kbd>). |
102 | | -
|
103 | | -## Contribute |
104 | | -Yes, that would be great! Open a pull request and we'll go from there! |
105 | | - |
106 | | -## License |
107 | | -MIT |
108 | | - |
109 | | -[vscode]: https://code.visualstudio.com/ |
110 | | -[nodejsdownload]: https://nodejs.org/download/ |
111 | | -[sourcemapquestion]: http://stackoverflow.com/questions/21719562/javascript-map-files-javascript-source-maps |
112 | | -[typings]: https://www.npmjs.com/package/typings |
| 1 | +vscode-typescript-boilerplate |
| 2 | +========================= |
| 3 | + |
| 4 | +This project provides a skeleton structure and IDE settings files to help with TypeScript development in [Visual Studio Code][vscode] (as of build 0.9.1). The project builds all TypeScript (`.ts`) files into a `build` directory in the root. |
| 5 | + |
| 6 | +## Project Structure |
| 7 | +The project currently provides the following features: |
| 8 | +* TypeScript compilation with Code's build command, or via `npm run build`, providing source maps |
| 9 | +* Mocha test structure, which can be run with Code or `npm test`, also with source maps |
| 10 | +* Error detection and navigation within Code for both build and test problems (see [Code Tasks](https://code.visualstudio.com/Docs/editor/tasks)) |
| 11 | +* Debug settings (_currently a bug is preventing this from being reliable_) |
| 12 | +* Type definitions provided by [`typings`][typings] |
| 13 | +* Custom type definitions ready for your own declarations |
| 14 | + |
| 15 | +### Project Structure |
| 16 | +``` |
| 17 | +.vscode/ |
| 18 | + launch.json # Defines launch tasks for debugging etc. |
| 19 | + tasks.json # Defines tasks available e.g. build & test |
| 20 | +
|
| 21 | +build/ # The output directory of JavaScript files |
| 22 | + # when built from TypeScript |
| 23 | + |
| 24 | +src/ # The root of all TypeScript source code |
| 25 | + app/ |
| 26 | + app.ts # The main entry point for the project. |
| 27 | + mymodule.ts # A sample module |
| 28 | + |
| 29 | + test/ |
| 30 | + app.test.ts # A sample test |
| 31 | + mymodule.test.ts # A sample module test with sinon spies |
| 32 | + |
| 33 | + typings/ # Typings downloaded using the typings command |
| 34 | + |
| 35 | + custom.d.ts # An example of custom ambient typings |
| 36 | + |
| 37 | + tsconfig.json # TypeScript compilation settings |
| 38 | + typings.json # TypeScript package definition file for typings |
| 39 | + |
| 40 | +package.json |
| 41 | +README.md |
| 42 | +``` |
| 43 | + |
| 44 | +## Getting Started |
| 45 | +This repository is ready for you to clone and start building your code around it. Simply follow the guide below. |
| 46 | + |
| 47 | +### Prerequisites |
| 48 | +1. Clone, fork, or [download](//github.com/Codesleuth/vscode-typescript-boilerplate/releases) the project. |
| 49 | +2. You need Node.js. [Go install it][nodejsdownload] |
| 50 | +3. Ensure the required dependencies have been installed: |
| 51 | + ```bash |
| 52 | + $ npm install |
| 53 | + ``` |
| 54 | + |
| 55 | +4. You will need [`typings`][typings] to allow the TypeScript to compile without errors. It's recommended to install this globally: |
| 56 | + ```bash |
| 57 | + $ npm install typings -g |
| 58 | + ``` |
| 59 | +
|
| 60 | +5. Change to the `src` directory and run `typings install` to fetch the required module type definitions defined in `typings.json`: |
| 61 | + ```bash |
| 62 | + $ cd src |
| 63 | + |
| 64 | + # if installed globally (recommended) |
| 65 | + $ typings install |
| 66 | +
|
| 67 | + # otherwise |
| 68 | + $ ../node_modules/.bin/typings install |
| 69 | + ``` |
| 70 | +
|
| 71 | +### Building |
| 72 | +1. Open VSCode, hit <kbd>CTRL</kbd>/<kbd>Cmd</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd>, type `open folder` and select the root of this repository |
| 73 | +2. Build with one of the following shortcuts: |
| 74 | + * Press <kbd>CTRL</kbd>/<kbd>Cmd</kbd>+<kbd>Shift</kbd>+<kbd>B</kbd> to build, which is declared in the `.vscode/tasks.json` file with the `isBuildCommand` marker |
| 75 | + * Press <kbd>CTRL</kbd>/<kbd>Cmd</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd> and select the `Tasks: Run Build Task` option |
| 76 | + * Press <kbd>CTRL</kbd>/<kbd>Cmd</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd>, delete the `>` and type `task build` |
| 77 | +3. If there were no errors, you should see a new directory, `build`, in the root with the following content: |
| 78 | +``` |
| 79 | +build/ |
| 80 | + app/ |
| 81 | + app.js |
| 82 | + app.js.map |
| 83 | + mymodule.js |
| 84 | + mymodule.js.map |
| 85 | + test/ |
| 86 | + app.test.js |
| 87 | + app.test.js.map |
| 88 | + mymodule.test.js |
| 89 | + mymodule.test.js.map |
| 90 | +``` |
| 91 | +
|
| 92 | +### Error Navigation |
| 93 | +After building or testing, errors are captured (defined in the `.vscode/tasks.json` file) and can be viewed with <kbd>CTRL</kbd>/<kbd>Command</kbd>+<kbd>Shift</kbd>+<kbd>M</kbd>. |
| 94 | +
|
| 95 | +Your `.ts` files have been compiled to `.js` files within the `build` directory, and each should have a `.js.map` _sourcemap_ file alongside it to allow stack traces to correctly report the line in the original file. See [this StackOverflow article][sourcemapquestion] for an overview of what a sourcemap is. |
| 96 | +
|
| 97 | +### Testing |
| 98 | +There are sample tests located in the `test` folder. You can run them by hitting <kbd>CTRL</kbd>/<kbd>Command</kbd>+<kbd>Shift</kbd>+<kbd>T</kbd> (or use the `Tasks` menu and run `Tasks: Run Test Task`) |
| 99 | +
|
| 100 | +### Running and Debugging |
| 101 | +To run the project in debug mode, simply hit <kbd>F5</kbd>! Place breakpoints in your TypeScript code and view them in the debugger (<kbd>CTRL</kbd>+<kbd>Shift</kbd>+<kbd>D</kbd> or <kbd>Cmd</kbd>+<kbd>Shift</kbd>+<kbd>D</kbd>). |
| 102 | +
|
| 103 | +## Contribute |
| 104 | +Yes, that would be great! Open a pull request and we'll go from there! |
| 105 | + |
| 106 | +## License |
| 107 | +MIT |
| 108 | + |
| 109 | +[vscode]: https://code.visualstudio.com/ |
| 110 | +[nodejsdownload]: https://nodejs.org/download/ |
| 111 | +[sourcemapquestion]: http://stackoverflow.com/questions/21719562/javascript-map-files-javascript-source-maps |
| 112 | +[typings]: https://www.npmjs.com/package/typings |
0 commit comments