diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index f426bd5..c3161e5 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -11,13 +11,12 @@ ### In-Depth -* Configuration variables -* TypeScript - * Strict mode - * TSLint -* Cookbook +* [Module bundling](./in-depth/module-bundling.md) +* [Configuration variables](./in-depth/configuration-variables.md) +* [TypeScript](./in-depth/typescript.md) +* [Cookbook](./in-depth/cookbook.md) * [TODO] --- -* FAQ & Troubleshooting +* [FAQ & Troubleshooting](./faq-troubleshooting.md) diff --git a/docs/faq-troubleshooting.md b/docs/faq-troubleshooting.md new file mode 100644 index 0000000..84e26fd --- /dev/null +++ b/docs/faq-troubleshooting.md @@ -0,0 +1,5 @@ +# FAQ & 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. + +[TODO] diff --git a/docs/getting-started/deploying.md b/docs/getting-started/deploying.md index 4f70415..8f2a5bb 100644 --- a/docs/getting-started/deploying.md +++ b/docs/getting-started/deploying.md @@ -1,6 +1,6 @@ # Deploying -## Building Your Configuration File +## Building your configuration file The starter kit builds your code using `rollup`, which uses a `screeps.json` file as its configuration file. A sample config file is provided within the project, to use it, simply make a copy and rename it to `screeps.json`. @@ -10,50 +10,11 @@ cp screeps.sample.json screeps.json > **IMPORTANT:** The `screeps.json` file contains your Screeps credentials. If you use any source control, **DO NOT** check in this file into your repository. -[TODO: move to 'in-depth'] +The `screeps.json` file is a JSON configuration file separated into multiple environments. We're going to focus on the `main` environment to get you starter. Fill in your Screeps credentials accordingly, along with your target branch. -The `screeps.json` file is a JSON configuration file that can be separated into multiple environments. We've given you three primary environments by default. +![deploying-1](img/deploying-1.png) -```json -{ - // Used for deploying to the main world - "main": { - "email": "you@provider.tld", - "password": "Password", - "protocol": "https", - "hostname": "screeps.com", - "port": 443, - "path": "/", - "branch": "main" - }, - // Used for deploying to Simulation mode - "sim": { - "email": "you@provider.tld", - "password": "Password", - "protocol": "https", - "hostname": "screeps.com", - "port": 443, - "path": "/", - "branch": "sim" - }, - // Used for deploying to a private server - "pserver": { - "email": "username", - "password": "Password", - "protocol": "http", - "hostname": "1.2.3.4", - "port": 21025, - "path": "/", - "branch": "main" - } -} -``` - -[/TODO: move to 'in-depth'] - -We're going to focus on the `main` environment as a starter. Fill in your Screeps credentials accordingly, along with your target branch. - -> **Note:** You don't have to manually create the branch in your Screeps client if it doesn't exist yet. `rollup` will do it for you. +> **Note:** You don't have to manually create the target branch in your Screeps client if it doesn't exist yet. `rollup-plugin-screeps` will do it for you. ## Running Your First Deploy @@ -65,6 +26,6 @@ npm run push-main You're done! Now go to your Screeps client and make sure your code is deployed properly. -![deploying-1](img/deploying-1.png) +![deploying-2](img/deploying-2.png) Ready for something extra? Read on. diff --git a/docs/getting-started/img/deploying-1.png b/docs/getting-started/img/deploying-1.png index 5d62597..9e04b63 100644 Binary files a/docs/getting-started/img/deploying-1.png and b/docs/getting-started/img/deploying-1.png differ diff --git a/docs/getting-started/img/deploying-2.png b/docs/getting-started/img/deploying-2.png new file mode 100644 index 0000000..5d62597 Binary files /dev/null and b/docs/getting-started/img/deploying-2.png differ diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md index ef228fd..2ddbe8b 100644 --- a/docs/getting-started/installation.md +++ b/docs/getting-started/installation.md @@ -8,7 +8,7 @@ You will need: - A Package Manager (Yarn or NPM) - Rollup (install with `npm intall -g rollup`) -## Installing `npm` Modules +## Installing `npm` modules Run the following the command to install the required packages and TypeScript declaration files: diff --git a/docs/in-depth/configuration-variables.md b/docs/in-depth/configuration-variables.md new file mode 100644 index 0000000..6102974 --- /dev/null +++ b/docs/in-depth/configuration-variables.md @@ -0,0 +1,40 @@ +# Configuration variables + +The `screeps.json` file is a JSON configuration file separated into multiple environments. We've given you three primary environments by default. + +```json +{ + // Used for deploying to the main world + "main": { + "email": "you@provider.tld", + "password": "Password", + "protocol": "https", + "hostname": "screeps.com", + "port": 443, + "path": "/", + "branch": "main" + }, + // Used for deploying to Simulation mode + "sim": { + "email": "you@provider.tld", + "password": "Password", + "protocol": "https", + "hostname": "screeps.com", + "port": 443, + "path": "/", + "branch": "sim" + }, + // Used for deploying to a private server + "pserver": { + "email": "username", + "password": "Password", + "protocol": "http", + "hostname": "1.2.3.4", + "port": 21025, + "path": "/", + "branch": "main" + } +} +``` + +[TODO: running environments] diff --git a/docs/in-depth/cookbook.md b/docs/in-depth/cookbook.md new file mode 100644 index 0000000..5adfbb3 --- /dev/null +++ b/docs/in-depth/cookbook.md @@ -0,0 +1,3 @@ +# Cookbook + +This section provides some slightly more advanced tips and tricks to help better improve your Screeps AI development workflow with TypeScript. diff --git a/docs/in-depth/module-bundling.md b/docs/in-depth/module-bundling.md new file mode 100644 index 0000000..bbce3c3 --- /dev/null +++ b/docs/in-depth/module-bundling.md @@ -0,0 +1,25 @@ +# Module bundling + +Bundling your Screeps codebase using module bundlers like [Webpack](https://webpack.js.org/) or [Rollup](https://rollupjs.org/) allows you to improve your Screeps AI development workflow. + +For instance, it allows you to easily include third-party libraries, like [screeps-profiler](https://github.com/screepers/screeps-profiler) and [Traveler](https://github.com/bonzaiferroni/Traveler). Instead of manually copy-pasting these libraries into your code, you can simply install it as an `npm` module: + +```bash +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. + +[TODO: more advantages of bundling code, if any] + +## 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) + +If you're still comfortable with using Webpack, the old version of the starter kit is available here (**TODO:** legacy branch link), but moving forward, no new features will be added to the Webpack version. diff --git a/docs/in-depth/typescript.md b/docs/in-depth/typescript.md new file mode 100644 index 0000000..53eca71 --- /dev/null +++ b/docs/in-depth/typescript.md @@ -0,0 +1,33 @@ +# TypeScript + +This section provides TypeScript-specific tips & tricks for you to make the best out of the ecosystem. + +## Strict mode + +The `--strict` compiler flag was introduced in TypeScript 2.3 which activates TypeScript's "strict mode". The strict mode sets all strict typechecking options to `true` by default. + +As of TypeScript 2.6, the affected options are: + +* `--noImplicitAny` +* `--noImplicitThis` +* `--alwaysStrict` +* `--strictNullChecks` +* `--strictFunctionTypes` + +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 + +## TSLint + +TSLint checks your TypeScript code for readability, maintainability, and functionality errors, and can also enforce coding style standards. + +[TODO: describe TSlint rules used in brief] + +### Customising TSLint + +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/ + +**More info about TSLint:** https://palantir.github.io/tslint/