GitBook: [master] 17 pages and 5 assets modified

docs/in-depth/contributing.md

@@ -0,0 +1,20 @@
+# Contributing to the docs
+
+We welcome contributions to the docs! We're looking for ways to make the starter kit documentation better, as well as many other tips and tricks about Screeps AI development in TypeScript. If you feel like some parts of the docs need fixing/improving, definitely create a pull request.
+
+For guidelines on contributing to the starter kit, [click here](https://github.com/screepers/screeps-typescript-starter/blob/master/CONTRIBUTING.md).
+
+## Gitbook
+
+Our documentation is built using [Gitbook](https://www.gitbook.com/), and are accessible [here](https://screepers.gitbooks.io/screeps-typescript-starter/). You can also start working on the docs locally by installing the Gitbook CLI.
+
+```bash
+npm install -g gitbook-cli
+```
+
+To run a local Gitbook server, run the following command on the project's root directory.
+
+```bash
+gitbook serve
+```
+

docs/in-depth/cookbook/README.md

@@ -1,3 +1,4 @@
 # Cookbook
 
 This section contains a community-maintained list of slightly more advanced tips and tricks to help better improve your Screeps AI development workflow with TypeScript. Feel free to [contribute your own](https://github.com/screepers/screeps-typescript-starter/tree/master/docs)!
+

docs/in-depth/cookbook/environment-variables.md

@@ -1,4 +1,4 @@
-# Managing deploys with environment variables
+# Environment variables
 
 Environment variables provide a more streamlined way to manage your build process. We can also use it to define "build toggles", or environment-based variables that will be injected into your scripts to be used during runtime.
 
@@ -6,7 +6,7 @@ Environment variables provide a more streamlined way to manage your build proces
 
 Let's say that we want to set `NODE_ENV` to `production` for uploading to our main branch, and `development` for uploading to our Simulation branch. First we'll catch the environment variable and assign the compile target based on it.
 
-```js
+```javascript
 // rollup.config.js
 
 const isProduction = process.env.NODE_ENV === 'production'
@@ -31,7 +31,7 @@ export default {
 
 Then we'll change the build tasks on `package.json` to pass the environment variable before running the rollup command.
 
-```json
+```javascript
 {
   "tasks": {
     "deploy-prod": "NODE_ENV=production rollup -c",
@@ -46,7 +46,7 @@ Then we'll change the build tasks on `package.json` to pass the environment vari
 npm install --save-dev cross-env
 ```
 
-```json
+```javascript
 {
   "tasks": {
     "deploy-prod": "cross-env NODE_ENV=production rollup -c",
@@ -59,7 +59,7 @@ Now let's give it a try! Run `npm run deploy-dev` or `npm run deploy-prod` and s
 
 ## Setting up build toggles
 
-You can also setup deployment-dependent variables (aka. "build toggles") that are injected to your code during build time to allow for more advanced optimisations like dead code elimination.
+You can also setup deployment-dependent variables \(aka. "build toggles"\) that are injected to your code during build time to allow for more advanced optimisations like dead code elimination.
 
 To do this, install `rollup-plugin-replace`.
 
@@ -73,7 +73,7 @@ $ yarn add --dev rollup-plugin-replace
 
 Then configure your `rollup.config.js` to include your desired variables.
 
-```js
+```javascript
 // rollup.config.js
 import replace from 'rollup-plugin-replace';
 
@@ -91,15 +91,15 @@ export default {
 };
 ```
 
-> **Note:** Generally, you need to ensure that `rollup-plugin-replace` goes *before* other plugins, so we can be sure Rollup replaces these variables correctly and the remaining plugins can apply any optimisations (e.g. dead code elimination) correctly.
-
-> **Note:** Because these values are evaluated once as a string (for the find-and-replace), and once as an expression, they need to be wrapped in `JSON.stringify`.
+> **Note:** Generally, you need to ensure that `rollup-plugin-replace` goes _before_ other plugins, so we can be sure Rollup replaces these variables correctly and the remaining plugins can apply any optimisations \(e.g. dead code elimination\) correctly.
+>
+> **Note:** Because these values are evaluated once as a string \(for the find-and-replace\), and once as an expression, they need to be wrapped in `JSON.stringify`.
 
 Variables set by this plugin will be replaced in the actual output JS code. When compiling your code, Rollup will replace the variable names with the output of the supplied expression or value.
 
 Once it's set up, you use it in your code.
 
-```ts
+```typescript
 // log the latest commit ID from git
 if (__REVISION__) {
   console.log(`Revision ID: ${__REVISION__}`)
@@ -115,13 +115,14 @@ export function loop() {
 
 ### Notes
 
-Since TypeScript won't recognise these variables if you pass it blindly into your code, you will still need to declare them in a type definition (.d.ts) file.
+Since TypeScript won't recognise these variables if you pass it blindly into your code, you will still need to declare them in a type definition \(.d.ts\) file.
 
-```ts
+```typescript
 // file.d.ts
 
 declare const __REVISION__: string;
 declare const __BUILD_TIME__: string;
 ```
 
-Also, be careful not to use too common of a name, because it will replace it throughout your code without warning. A good standard is to make the variables all caps, and surrounded by double underscores, so they stand out (e.g. `__REVISION__`).
+Also, be careful not to use too common of a name, because it will replace it throughout your code without warning. A good standard is to make the variables all caps, and surrounded by double underscores, so they stand out \(e.g. `__REVISION__`\).
+

docs/in-depth/cookbook/one-line-powershell.md

@@ -1,19 +1,22 @@
 # One-line PowerShell setup
 
-> **Note:** As of v3.0, this no longer works. This issue is being tracked [here](https://github.com/ChrisTaylorRocks/screeps-typescript-starter-setup/issues/1).
+{% hint style="warning" %}
+**Note:** As of v3.0, this no longer works. This issue is being tracked [here](https://github.com/ChrisTaylorRocks/screeps-typescript-starter-setup/issues/1).
+{% endhint %}
 
 [@ChrisTaylorRocks](https://github.com/ChrisTaylorRocks) has made a PowerShell script to get the starter kit up and running with a single command. Go check it out [here](https://github.com/ChrisTaylorRocks/screeps-typescript-starter-setup)!
 
 ## Usage
 
-PowerShell < 5.0:
+PowerShell &lt; 5.0:
 
-```
+```text
 PS> (new-object Net.WebClient).DownloadString('http://bit.ly/2z2QDJI') | iex; New-ScreepsTypeScriptSetup
 ```
 
 PowerShell 5.0+:
 
-```
+```text
 PS> curl http://bit.ly/2z2QDJI | iex; New-ScreepsTypeScriptSetup
 ```
+

docs/in-depth/deploy-destinations.md

@@ -1,8 +1,8 @@
-# Deploy destination
+# Deploy destinations
 
 The `screeps.json` file is a JSON configuration file separated into multiple deploy destinations. We've given you three primary destinations by default.
 
-```json
+```javascript
 {
   // Used for deploying to the main world
   "main": {
@@ -44,3 +44,4 @@ rollup -c --environment DEST:main
 ```
 
 Omitting the destination will perform a dry run, which will compile and bundle the code without uploading it.
+

docs/in-depth/module-bundling.md

@@ -10,27 +10,27 @@ npm install screeps-profiler
 
 Then you can import these libraries just like you would any other `npm` module. When you run the module bundler, it will bundle up all your files and third-party modules into one single JS file.
 
-Some module bundlers even support performing further optimisations like eliminating unused module functions from your final bundled code (aka. _tree-shaking_), reducing the size of your final bundled JS even further.
+Some module bundlers even support performing further optimisations like eliminating unused module functions from your final bundled code \(aka. _tree-shaking_\), reducing the size of your final bundled JS even further.
 
 ## Rollup
 
 From version 3.0 onwards, the starter kit uses Rollup as its main module bundler. Some useful features of Rollup include:
 
-* Bundled modules are entirely flat (no weird boilerplate code emitted like in Webpack)
-* Advanced tree-shaking (eliminates unused modules from the final bundle)
-* Simpler configuration (compared to Webpack)
+* Bundled modules are entirely flat \(no weird boilerplate code emitted like in Webpack\)
+* Advanced tree-shaking \(eliminates unused modules from the final bundle\)
+* Simpler configuration \(compared to Webpack\)
 
 If you're still comfortable with using Webpack, the old version of the starter kit is available [here](https://github.com/screepers/screeps-typescript-starter/tree/legacy/webpack), but moving forward, no new features will be added to the Webpack version.
 
 ### Note: Rollup and named exports
 
-By default, Rollup recognises ES6 modules. This means that some adjustments are necessary in order for Rollup to work well with CommonJS modules, particularly those with named exports like `screeps-profiler`. (See [#77](https://github.com/screepers/screeps-typescript-starter/issues/77))
+By default, Rollup recognises ES6 modules. This means that some adjustments are necessary in order for Rollup to work well with CommonJS modules, particularly those with named exports like `screeps-profiler`. \(See [\#77](https://github.com/screepers/screeps-typescript-starter/issues/77)\)
 
 In this case, you will have to manually specify the named exports you use, which is where the `rollup-plugin-commonjs` plugin comes into play. This plugin resolves any CommonJS modules and converts them to ES6 modules, which can be bundled.
 
 Simply include the modules you want to bundle complete with its named exports, like so:
 
-```js
+```javascript
 commonjs({
   namedExports: {
     // left-hand side can be an absolute path, a path
@@ -42,3 +42,4 @@ commonjs({
 ```
 
 **For more info:** [`rollup-plugin-commonjs` docs](https://github.com/rollup/rollup-plugin-commonjs)
+

docs/in-depth/prettier.md

@@ -1,10 +1,10 @@
-# Code formatting with Prettier
+# Prettier
 
 [Prettier](https://prettier.io/) is an automatic code formatter which supports various languages, including TypeScript. It also has extensions for various text editors like [VSCode](https://github.com/prettier/prettier-vscode), [Atom](https://github.com/prettier/prettier-atom), and even [Vim](https://github.com/prettier/vim-prettier). If you have installed these extensions, it will use Prettier's service to automatically format your code after saving.
 
 If you would rather not use Prettier instead, you can easily disable it too. In VSCode, open `.vscode/settings.json`, then change the `"editor.formatOnSave"` option to `false`:
 
-```json
+```javascript
 {
   "[json]": {
     "editor.formatOnSave": false
@@ -22,7 +22,7 @@ If you would rather not use Prettier instead, you can easily disable it too. In
 
 The `.prettierrc` file configures how Prettier formats your code. By default we use the following options.
 
-```json
+```javascript
 {
   "semi": true,
   "tabWidth": 2,
@@ -34,7 +34,7 @@ The `.prettierrc` file configures how Prettier formats your code. By default we
 
 We can use `tslint-config-prettier` to override some TSLint rules with its Prettier counterparts. In your `tslint.json` file, extend `tslint-config-prettier`.
 
-```json
+```javascript
 {
   "extends" : [
     "tslint:recommended",
@@ -49,7 +49,7 @@ To make Prettier error out on formatting errors, we can also use `tslint-plugin-
 yarn add --dev tslint-plugin-prettier
 ```
 
-```json
+```javascript
 {
   "rulesDirectory": ["tslint-plugin-prettier"],
   "rules": {
@@ -57,3 +57,4 @@ yarn add --dev tslint-plugin-prettier
   }
 }
 ```
+

docs/in-depth/troubleshooting.md

@@ -0,0 +1,23 @@
+# Troubleshooting
+
+This page outlines any common issues that you'll run into while setting up the TypeScript starter, as well as how to fix them.
+
+## Unable to upload code to Screeps private server
+
+If you're getting the following error:
+
+```text
+(node:80116) UnhandledPromiseRejectionWarning: Unhandled promise rejection (rejection id: 1): Error: Cannot POST /api/auth/signin
+```
+
+Make sure you have [screepsmod-auth](https://github.com/ScreepsMods/screepsmod-auth) installed on your private server, and you've set a password on the account in your private server as well.
+
+## Unable to extend type interfaces \(e.g. `Game`, `Memory`\)
+
+Make sure you declare any extensions to the type interfaces as an [_ambient declaration_](https://stackoverflow.com/a/40916055). You can either:
+
+* put them inside a `*.d.ts` file, or
+* in an existing `.ts` file \(with at least one `import` or `export`\), you can use `declare global { interface CreepMemory { ... } }` to accomplish the same effect.
+
+**For more info:** [https://github.com/screepers/typed-screeps/issues/27](https://github.com/screepers/typed-screeps/issues/27)
+

docs/in-depth/typescript.md

@@ -6,7 +6,7 @@ Static type checkers like TypeScript and [Flow](https://flow.org/) help reduce t
 
 To read more about how TypeScript can help you in Screeps, read [this Screeps World article](https://screepsworld.com/2017/07/typescreeps-getting-started-with-ts-in-screeps/) by [@bonzaiferroni](https://github.com/bonzaiferroni).
 
-This section provides TypeScript-specific tips & tricks for you to make the best out of the ecosystem.
+This section provides TypeScript-specific tips & tricks for you to make the best out of the ecosystem.
 
 ## Strict mode
 
@@ -23,7 +23,7 @@ As of TypeScript 2.7, the affected options are:
 
 Starting from version 2.0 of the starter kit, we've enabled the `--strict` flag in `tsconfig.json`. If this gives you compile time errors, you can try setting `"strict"` to `false`, or by overriding one or more of the options listed above.
 
-**For more info:** https://blog.mariusschulz.com/2017/06/09/typescript-2-3-the-strict-compiler-option
+**For more info:** [https://blog.mariusschulz.com/2017/06/09/typescript-2-3-the-strict-compiler-option](https://blog.mariusschulz.com/2017/06/09/typescript-2-3-the-strict-compiler-option)
 
 ## TSLint
 
@@ -42,6 +42,7 @@ We've made some changes to these rules, which we considered necessary and/or rel
 
 You can also customise your `tslint.json` file to match the preferences of your codebase. Click [here](https://palantir.github.io/tslint/usage/configuration/), to find out how, and click [here](https://palantir.github.io/tslint/rules/) for a complete list of rules available.
 
-If you believe that some rules should not apply to a part of your code (e.g. for one-off cases like having to use `require()` to include a module), you can use flags to let TSLint know about it: https://palantir.github.io/tslint/usage/rule-flags/
+If you believe that some rules should not apply to a part of your code \(e.g. for one-off cases like having to use `require()` to include a module\), you can use flags to let TSLint know about it: [https://palantir.github.io/tslint/usage/rule-flags/](https://palantir.github.io/tslint/usage/rule-flags/)
+
+**More info about TSLint:** [https://palantir.github.io/tslint/](https://palantir.github.io/tslint/)
 
-**More info about TSLint:** https://palantir.github.io/tslint/