From efadd81dad09b79ccde5007f3ba78131481d1b83 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Tim=20D=C3=BCsterhus?= Date: Tue, 13 Apr 2021 12:44:12 +0200 Subject: [PATCH] Add basic TypeScript documentation see #96 --- docs/javascript/general-usage.md | 2 + docs/javascript/typescript.md | 173 +++++++++++++++++++++++++++++ docs/migration/wsc53/javascript.md | 13 ++- mkdocs.yml | 5 +- 4 files changed, 190 insertions(+), 3 deletions(-) create mode 100644 docs/javascript/typescript.md diff --git a/docs/javascript/general-usage.md b/docs/javascript/general-usage.md index 8406fe85..8b2b5200 100644 --- a/docs/javascript/general-usage.md +++ b/docs/javascript/general-usage.md @@ -1,5 +1,7 @@ # General JavaScript Usage +!!! info "WoltLab Suite 5.4 introduced support for TypeScript, migrating all existing modules to TypeScript. The JavaScript section of the documentation is not yet updated to account for the changes, possibly explaining concepts that cannot be applied as-is when writing TypeScript. You can learn about basic TypeScript use in WoltLab Suite, such as consuming WoltLab Suite’s types in own packages, within in [the TypeScript section](typescript.md)." + ## The History of the Legacy API The WoltLab Suite 3.0 [introduced a new API](new-api_writing-a-module.md) based on AMD-Modules diff --git a/docs/javascript/typescript.md b/docs/javascript/typescript.md new file mode 100644 index 00000000..66b6f135 --- /dev/null +++ b/docs/javascript/typescript.md @@ -0,0 +1,173 @@ +# TypeScript + +## Consuming WoltLab Suite’s Types + +To consume the types of WoltLab Suite you will need to install the [WoltLab/WCF](https://github.com/WoltLab/WCF) using npm using a git URL that refers to the appropriate branch. + +A full `package.json` that includes WoltLab Suite, TypeScript, eslint and Prettier could look like the following. + +```json +{ + "devDependencies": { + "@typescript-eslint/eslint-plugin": "^4.6.1", + "@typescript-eslint/parser": "^4.6.1", + "eslint": "^7.12.1", + "eslint-config-prettier": "^6.15.0", + "prettier": "^2.1.2", + "tslib": "^2.0.3", + "typescript": "^4.1.3" + }, + "dependencies": { + "@woltlab/wcf": "https://github.com/WoltLab/WCF.git#master" + } +} +``` + +After installing the types using npm you will also need to configure tsconfig.json to take the types into account. +To do so you will need to add them to the `compilerOptions.paths` option. +A full `tsconfig.json` that matches the configuration of WoltLab Suite could look like the following. + +```json +{ + "include": [ + "node_modules/@woltlab/wcf/global.d.ts", + "ts/**/*" + ], + "compilerOptions": { + "target": "es2017", + "module": "amd", + "rootDir": "ts/", + "outDir": "files/js/", + "lib": [ + "dom", + "es2017" + ], + "strictNullChecks": true, + "moduleResolution": "node", + "esModuleInterop": true, + "noImplicitThis": true, + "strictBindCallApply": true, + "baseUrl": ".", + "paths": { + "*": [ + "node_modules/@woltlab/wcf/ts/*" + ] + }, + "importHelpers": true + } +} +``` + +After this initial set-up you would place your TypeScript source files into the `ts/` folder of your project. +The generated JavaScript target files will be placed into `files/js/` and thus will be installed by the [file PIP](../package/pip/file.md). + +## Additional Tools + +WoltLab Suite uses additional tools to ensure the high quality and a consistent code style of the TypeScript modules. +The current configuration of these tools is as follows. +It is recommended to re-use this configuration as is. + +### .prettierrc + +```yml +trailingComma: all +printWidth: 120 +``` + +### .eslintrc.js + +```javascript +module.exports = { + root: true, + parser: "@typescript-eslint/parser", + parserOptions: { + tsconfigRootDir: __dirname, + project: ["./tsconfig.json"] + }, + plugins: ["@typescript-eslint"], + extends: [ + "eslint:recommended", + "plugin:@typescript-eslint/recommended", + "plugin:@typescript-eslint/recommended-requiring-type-checking", + "prettier", + "prettier/@typescript-eslint" + ], + rules: { + "@typescript-eslint/ban-types": [ + "error", { + types: { + "object": false + }, + extendDefaults: true + } + ], + "@typescript-eslint/no-explicit-any": 0, + "@typescript-eslint/no-non-null-assertion": 0, + "@typescript-eslint/no-unsafe-assignment": 0, + "@typescript-eslint/no-unsafe-call": 0, + "@typescript-eslint/no-unsafe-member-access": 0, + "@typescript-eslint/no-unsafe-return": 0, + "@typescript-eslint/no-unused-vars": [ + "error", { + "argsIgnorePattern": "^_" + } + ] + } +}; +``` + +### .eslintignore + +```gitignore +**/*.js +``` + +### .gitattributes + +This `.gitattributes` configuration will automatically collapse the generated JavaScript target files in GitHub’s Diff view. +You will not need it if you do not use git or GitHub. + +```gitattributes +files/js/**/*.js linguist-generated +``` + +## Writing a simple module + +After completing this initial set-up you can start writing your first TypeScript module. +The TypeScript compiler can be launched in Watch Mode by running `npx tsc -w`. + +WoltLab Suite’s modules can be imported using the standard ECMAScript module import syntax by specifying the full module name. +The public API of the module can also be exported using the standard ECMASCript module export syntax. + +```typescript +import * as Language from "WoltLabSuite/Core/Language"; + +export function run() { + alert(Language.get("wcf.foo.bar")); +} +``` + +This simple example module will compile to plain JavaScript that is compatible with the AMD loader that is used by WoltLab Suite. + +```javascript +define(["require", "exports", "tslib", "WoltLabSuite/Core/Language"], function (require, exports, tslib_1, Language) { + "use strict"; + Object.defineProperty(exports, "__esModule", { value: true }); + exports.run = void 0; + Language = tslib_1.__importStar(Language); + function run() { + alert(Language.get("wcf.foo.bar")); + } + exports.run = run; +}); +``` + +Within templates it can be consumed as follows. + +```html + +``` diff --git a/docs/migration/wsc53/javascript.md b/docs/migration/wsc53/javascript.md index 12e72d67..35f49872 100644 --- a/docs/migration/wsc53/javascript.md +++ b/docs/migration/wsc53/javascript.md @@ -1,4 +1,15 @@ -# Migrating from WSC 5.3 - JavaScript +# Migrating from WSC 5.3 - TypeScript and JavaScript + +## TypeScript + +WoltLab Suite 5.4 introduces TypeScript support. +Learn about consuming WoltLab Suite’s types in [the TypeScript section](../../javascript/typescript.md) of the JavaScript API documentation. + +The JavaScript API documentation will be updated to properly take into account the changes that came with the new TypeScript support in the future. +Existing AMD based modules have been migrated to TypeScript, but will expose the existing and known API. + +It is recommended that you migrate your custom packages to make use of TypeScript. +It will make consuming newly written modules that properly leverage TypeScript’s features much more pleasant and will also ease using existing modules due to proper autocompletion and type checking. ## `WCF_CLICK_EVENT` diff --git a/mkdocs.yml b/mkdocs.yml index bf023651..ae8cc219 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -44,8 +44,9 @@ nav: - 'Templates': 'view/templates.md' - 'CSS': 'view/css.md' - - 'JavaScript API': + - 'TypeScript and JavaScript API': - 'General Usage': 'javascript/general-usage.md' + - 'TypeScript': 'javascript/typescript.md' - 'New API': - 'Writing a module': 'javascript/new-api_writing-a-module.md' - 'Data Structures': 'javascript/new-api_data-structures.md' @@ -101,7 +102,7 @@ nav: - 'Migrating from WSC 5.3': - 'PHP API': 'migration/wsc53/php.md' - 'Session Handling and Authentication': 'migration/wsc53/session.md' - - 'JavaScript': 'migration/wsc53/javascript.md' + - 'TypeScript and JavaScript': 'migration/wsc53/javascript.md' - 'Templates': 'migration/wsc53/templates.md' - 'Third Party Libraries': 'migration/wsc53/libraries.md' - 'Migrating from WSC 5.2': -- 2.20.1