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 {jinja{ codebox(
  10   title="package.json",
  11   language="json",
  12   filepath="typescript/package.json"
  13 ) }}
  14
  15 After installing the types using npm, you will also need to configure `tsconfig.json` to take the types into account.
  16 To do so, you will need to add them to the `compilerOptions.paths` option.
  17 A complete `tsconfig.json` file that matches the configuration of WoltLab Suite could look like the following.
  18
  19 {jinja{ codebox(
  20   title="tsconfig.json",
  21   language="json",
  22   filepath="typescript/tsconfig.json"
  23 ) }}
  24
  25 After this initial set-up, you would place your TypeScript source files into the `ts/` folder of your project.
  26 The generated JavaScript target files will be placed into `files/js/` and thus will be installed by the [file PIP](../package/pip/file.md).
  27
  28 ## Additional Tools
  29
  30 WoltLab Suite uses additional tools to ensure the high quality and a consistent code style of the TypeScript modules.
  31 The current configuration of these tools is as follows.
  32 It is recommended to re-use this configuration as is.
  33
  34 {jinja{ codebox(
  35   title=".prettierrc",
  36   language="yml",
  37   filepath="typescript/.prettierrc"
  38 ) }}
  39
  40 {jinja{ codebox(
  41   title=".eslintrc.js",
  42   language="javascript",
  43   filepath="typescript/.eslintrc.js"
  44 ) }}
  45
  46 {jinja{ codebox(
  47   title=".eslintignore",
  48   language="gitignore",
  49   filepath="typescript/.eslintignore"
  50 ) }}
  51
  52 This `.gitattributes` configuration will automatically collapse the generated JavaScript target files in GitHub’s Diff view.
  53 You will not need it if you do not use git or GitHub.
  54
  55 {jinja{ codebox(
  56   title=".gitattributes",
  57   language="gitattributes",
  58   filepath="typescript/.gitattributes"
  59 ) }}
  60
  61 ## Writing a simple module
  62
  63 After completing this initial set-up you can start writing your first TypeScript module.
  64 The TypeScript compiler can be launched in Watch Mode by running `npx tsc -w`.
  65
  66 WoltLab Suite’s modules can be imported using the standard ECMAScript module import syntax by specifying the full module name.
  67 The public API of the module can also be exported using the standard ECMAScript module export syntax.
  68
  69 {jinja{ codebox(
  70   title="ts/Example.ts",
  71   language="typescript",
  72   filepath="typescript/Example.ts"
  73 ) }}
  74
  75 This simple example module will compile to plain JavaScript that is compatible with the AMD loader that is used by WoltLab Suite.
  76
  77 {jinja{ codebox(
  78   title="files/js/Example.js",
  79   language="javascript",
  80   filepath="typescript/Example.js"
  81 ) }}
  82
  83 Within templates it can be consumed as follows.
  84
  85 ```html
  86 <script data-relocate="true">
  87   require(["Example"], (Example) => {
  88     Example.run(); // Alerts the contents of the `wcf.foo.bar` phrase.
  89   });
  90 </script>
  91 ```