docs/javascript/typescript.md

   1 # TypeScript
   2
   3 ## Consuming WoltLab Suite’s Types
   4
   5 To consume the types of WoltLab Suite, you will need to install the `@woltlab/wcf` npm package using a git URL that refers to the appropriate branch of [WoltLab/WCF](https://github.com/WoltLab/WCF).
   6
   7 A full `package.json` that includes WoltLab Suite, TypeScript, eslint and Prettier could look like the following.
   8
   9 ```json
  10 {
  11   "devDependencies": {
  12     "@typescript-eslint/eslint-plugin": "^4.6.1",
  13     "@typescript-eslint/parser": "^4.6.1",
  14     "eslint": "^7.12.1",
  15     "eslint-config-prettier": "^6.15.0",
  16     "prettier": "^2.1.2",
  17     "tslib": "^2.0.3",
  18     "typescript": "^4.1.3"
  19   },
  20   "dependencies": {
  21     "@woltlab/wcf": "https://github.com/WoltLab/WCF.git#master"
  22   }
  23 }
  24 ```
  25
  26 After installing the types using npm, you will also need to configure `tsconfig.json` to take the types into account.
  27 To do so, you will need to add them to the `compilerOptions.paths` option.
  28 A complete `tsconfig.json` file that matches the configuration of WoltLab Suite could look like the following.
  29
  30 ```json
  31 {
  32   "include": [
  33     "node_modules/@woltlab/wcf/global.d.ts",
  34     "ts/**/*"
  35   ],
  36   "compilerOptions": {
  37     "target": "es2017",
  38     "module": "amd",
  39     "rootDir": "ts/",
  40     "outDir": "files/js/",
  41     "lib": [
  42       "dom",
  43       "es2017"
  44     ],
  45     "strictNullChecks": true,
  46     "moduleResolution": "node",
  47     "esModuleInterop": true,
  48     "noImplicitThis": true,
  49     "strictBindCallApply": true,
  50     "baseUrl": ".",
  51     "paths": {
  52       "*": [
  53         "node_modules/@woltlab/wcf/ts/*"
  54       ]
  55     },
  56     "importHelpers": true
  57   }
  58 }
  59 ```
  60
  61 After this initial set-up, you would place your TypeScript source files into the `ts/` folder of your project.
  62 The generated JavaScript target files will be placed into `files/js/` and thus will be installed by the [file PIP](../package/pip/file.md).
  63
  64 ## Additional Tools
  65
  66 WoltLab Suite uses additional tools to ensure the high quality and a consistent code style of the TypeScript modules.
  67 The current configuration of these tools is as follows.
  68 It is recommended to re-use this configuration as is.
  69
  70 ### .prettierrc
  71
  72 ```yml
  73 trailingComma: all
  74 printWidth: 120
  75 ```
  76
  77 ### .eslintrc.js
  78
  79 ```javascript
  80 module.exports = {
  81   root: true,
  82   parser: "@typescript-eslint/parser",
  83   parserOptions: {
  84     tsconfigRootDir: __dirname,
  85     project: ["./tsconfig.json"]
  86   },
  87   plugins: ["@typescript-eslint"],
  88   extends: [
  89     "eslint:recommended",
  90     "plugin:@typescript-eslint/recommended",
  91     "plugin:@typescript-eslint/recommended-requiring-type-checking",
  92     "prettier",
  93     "prettier/@typescript-eslint"
  94   ],
  95   rules: {
  96     "@typescript-eslint/ban-types": [
  97       "error", {
  98         types: {
  99           "object": false
 100         },
 101         extendDefaults: true
 102       }
 103     ],
 104     "@typescript-eslint/no-explicit-any": 0,
 105     "@typescript-eslint/no-non-null-assertion": 0,
 106     "@typescript-eslint/no-unsafe-assignment": 0,
 107     "@typescript-eslint/no-unsafe-call": 0,
 108     "@typescript-eslint/no-unsafe-member-access": 0,
 109     "@typescript-eslint/no-unsafe-return": 0,
 110     "@typescript-eslint/no-unused-vars": [
 111       "error", {
 112         "argsIgnorePattern": "^_"
 113       }
 114     ]
 115   }
 116 };
 117 ```
 118
 119 ### .eslintignore
 120
 121 ```gitignore
 122 **/*.js
 123 ```
 124
 125 ### .gitattributes
 126
 127 This `.gitattributes` configuration will automatically collapse the generated JavaScript target files in GitHub’s Diff view.
 128 You will not need it if you do not use git or GitHub.
 129
 130 ```gitattributes
 131 files/js/**/*.js linguist-generated
 132 ```
 133
 134 ## Writing a simple module
 135
 136 After completing this initial set-up you can start writing your first TypeScript module.
 137 The TypeScript compiler can be launched in Watch Mode by running `npx tsc -w`.
 138
 139 WoltLab Suite’s modules can be imported using the standard ECMAScript module import syntax by specifying the full module name.
 140 The public API of the module can also be exported using the standard ECMAScript module export syntax.
 141
 142 ```typescript
 143 import * as Language from "WoltLabSuite/Core/Language";
 144
 145 export function run() {
 146   alert(Language.get("wcf.foo.bar"));
 147 }
 148 ```
 149
 150 This simple example module will compile to plain JavaScript that is compatible with the AMD loader that is used by WoltLab Suite.
 151
 152 ```javascript
 153 define(["require", "exports", "tslib", "WoltLabSuite/Core/Language"], function (require, exports, tslib_1, Language) {
 154     "use strict";
 155     Object.defineProperty(exports, "__esModule", { value: true });
 156     exports.run = void 0;
 157     Language = tslib_1.__importStar(Language);
 158     function run() {
 159         alert(Language.get("wcf.foo.bar"));
 160     }
 161     exports.run = run;
 162 });
 163 ```
 164
 165 Within templates it can be consumed as follows.
 166
 167 ```html
 168 <script data-relocate="true">
 169   require(["Example"], (Example) => {
 170     Example.run(); // Alerts the contents of the `wcf.foo.bar` phrase.
 171   });
 172 </script>
 173 ```