paulmataruso/zulip
1
0
Fork 0
mirror of https://github.com/zulip/zulip.git synced 2025-11-09 08:26:11 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: Update documentation on JavaScript modules.

Browse Source 
Signed-off-by: Anders Kaseorg <anders@zulip.com>
This commit is contained in:
Anders Kaseorg
2021-03-29 11:33:52 -07:00
committed by Tim Abbott
parent 056b715765
commit 8798b0a134
1 changed files with 29 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files

48
docs/subsystems/html-css.md
View File

@@ -237,32 +237,42 @@ server is restarted, files are copied into that directory.
without breaking the rendering of old messages (or doing a without breaking the rendering of old messages (or doing a
mass-rerender of old messages). mass-rerender of old messages).
### CommonJS/TypeScript modules ### ES6/TypeScript modules
Webpack provides seamless interoperability between different module JavaScript modules in the frontend are [ES6
systems such as CommonJS, AMD and ES6. Our JS files are written in the modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules)
CommonJS format, which specifies public functions and variables as that are [transpiled by
properties of the special `module.exports` object. We also currently webpack](https://webpack.js.org/api/module-methods/#es6-recommended).
assign said object to the global `window` variable, which is a hack Any variable, function, etc. can be made public by adding the
allowing us to use modules without importing them with the `require()` [`export`
statement. keyword](https://developer.mozilla.org/en-US/docs/web/javascript/reference/statements/export),
and consumed from another module using the [`import`
statement](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import).
New modules should ideally be written in TypeScript (though in cases New modules should ideally be written in TypeScript (though in cases
where one is moving code from an existing JavaScript module, the new where one is moving code from an existing JavaScript module, the new
commit should just move the code, not translate it to TypeScript). commit should just move the code, not translate it to TypeScript).
TypeScript provides more accurate information to development tools, TypeScript provides more accurate information to development tools,
allowing for better refactoring, auto-completion and static allowing for better refactoring, auto-completion and static analysis.
analysis. TypeScript uses an ES6-like module system. Any declaration TypeScript also uses the ES6 module system. See our documentation on
can be made public by adding the `export` keyword. Consuming [TypeScript static types](../testing/typescript).
variables, functions, etc exported from another module should be done
with the `import` statement as oppose to accessing them from the
global `window` scope. Internally our TypeScript compiler is
configured to transpile TS to the ES6 module system.
Read more about these module systems here: Webpack does not ordinarily allow modules to be accessed directly from
* [TypeScript modules](https://www.typescriptlang.org/docs/handbook/modules.html) the browser console, but for debugging convenience, we have a custom
* [CommonJS](https://nodejs.org/api/modules.html#modules_modules) webpack plugin (`tools/debug-require-webpack-plugin.ts`) that exposes
a version of the `require()` function to the development environment
browser console for this purpose. For example, you can access our
`people` module by evaluating `people =
require("./static/js/people")`, or the third-party `lodash` module
with `_ = require("lodash")`. This mechanism is **not** a stable API
and should not be used for any purpose other than interactive
debugging.
We have one module, `zulip_test`, that’s exposed as a global variable
using `expose-loader` for direct use in Puppeteer tests and in the
production browser console. If you need to access a variable or
function in those scenarios, add it to `zulip_test`. This is also
**not** a stable API.
[Jinja2]: http://jinja.pocoo.org/ [Jinja2]: http://jinja.pocoo.org/
[Handlebars]: https://handlebarsjs.com/ [Handlebars]: https://handlebarsjs.com/