1 | > __[JIRA](https://issues.jenkins-ci.org/browse/JENKINS/component/21133)__
|
2 |
|
3 | This is a JavaScript "module bundle" loader for Jenkins ([NPM] package) i.e. a loader for loading a JavaScript file that contains one or more
|
4 | [CommonJS]/[node.js] style modules in a single HTTP request (i.e. a "bundle").
|
5 |
|
6 | For more information on "module bundle" loading, read the
|
7 | <a href="https://github.com/jenkinsci/js-modules/blob/master/FAQs.md#what-does-module-loading-mean">What does "module loading" mean</a> FAQ.
|
8 |
|
9 | Install Package:
|
10 |
|
11 | ```
|
12 | npm install --save @jenkins-cd/js-modules
|
13 | ```
|
14 | __Table of Contents__:
|
15 | <p>
|
16 | <ul>
|
17 | <a href="#problem--motivation">Problem / Motivation</a><br/>
|
18 | <a href="https://github.com/jenkinsci/js-modules/blob/master/FAQs.md#do-i-really-need-to-learn-all-this-new-stuff">Do I really need to learn all this "new" stuff?</a><br/>
|
19 | <a href="#about-jenkins-modules">About Jenkins Modules</a><br/>
|
20 | <a href="https://github.com/jenkinsci/js-samples">Building Jenkins Plugins to use Modularized JavaScript</a><br/>
|
21 | <a href="#support-modules">Support Modules</a><br/>
|
22 | <a href="#framework-libs-jenkinscijs-libs">Framework Libs (jenkinsci/js-libs)</a><br/>
|
23 | <a href="https://github.com/jenkinsci/js-modules/issues">Enhancement/Issue Tracking</a><br/>
|
24 | <a href="FAQs.md">FAQs</a><br/>
|
25 | <a href="https://issues.jenkins-ci.org/browse/JENKINS/component/21133">JIRA</a><br/>
|
26 | </ul>
|
27 | </p>
|
28 |
|
29 | <hr/>
|
30 |
|
31 | # Problem / Motivation
|
32 | For the most part, the Jenkins GUI is constructed on the server side from [Jelly] files ([Stapler] etc). Client-side
|
33 | JavaScript has not played a big part in the Jenkins GUI.
|
34 |
|
35 | If the Jenkins GUI is to be modernized and improved (from a user experience perspective), client-side JavaScript
|
36 | needs to be able to play a bigger part. If that's so, we need to modernize/improve the development patterns around how
|
37 | JavaScript is currently used in Jenkins.
|
38 |
|
39 | As we see it, the main issues today are:
|
40 |
|
41 | 1. __Modularity__: Jenkins currently has no concept of modularity when it comes to the JavaScript code used in the GUI. All of the JavaScript is concentrated mainly in a single JavaScript file i.e. `hudson-behaviour.js`.
|
42 | 1. __Anti-Patterns__: Too much JavaScript code is bound into the global scope, creating a litany of well known issues.
|
43 | 1. __Testability__: Not easy to write JavaScript unit tests. The only way JavaScript is tested is via `JenkinsRule` (HtmlUnit and it's `WebClient`).
|
44 | 1. __Multiple versions of Framework Libraries__: One version of Prototype/jQuery doesn’t fit all. We need a way of supporting multiple versions of the same library (e.g. jQuery) in a way that works in the browser, "detached" from the global scope. We need to be able to introduce new versions of libraries (and deprecate old versions) in an orderly fashion.
|
45 |
|
46 | These are the problems that `js-modules` (this [NPM] package) is targeted at helping to solve.
|
47 |
|
48 | It is hoped that `js-modules` will help those that are interested (see next section) in maintaining __modular__,
|
49 | __unit testable__, __evolvable__ (see note below) JavaScript code that runs in a more predictable/stable environment that
|
50 | is more immune to plugin updates etc (e.g. an upgrade to the
|
51 | [jQuery plugin](https://wiki.jenkins-ci.org/display/JENKINS/jQuery+Plugin) doesn't break the plugin GUI).
|
52 | Using [CommonJS] style modularity also makes it possible to __more easily leverage the growing set of publicly available
|
53 | [NPM]/[node.js] packages__, which is a huge benefit.
|
54 |
|
55 | > __What do we mean by "evolvable"?__: `js-modules` makes it possible to safely run multiple versions of core JavaScript Framework libs on the same page (jQuery, Bootstrap etc). This makes it possible for modular code (built on `js-modules`) to depend on an explicit version of a JS lib that is guaranteed to remain available on e.g. plugin upgrades. Conversely, the same modular code can upgrade the version of a lib it depends on without effecting other modular code that still depends on an older version.
|
56 |
|
57 | # Do I need to learn all this "new" stuff?
|
58 | No, this is totally optional. [See FAQ](https://github.com/jenkinsci/js-modules/blob/master/FAQs.md#do-i-really-need-to-learn-all-this-new-stuff)
|
59 |
|
60 | # About Jenkins Modules
|
61 |
|
62 | The following slides attempt to bring you through `js-modules` in some more detail.
|
63 |
|
64 | <p align="center">
|
65 | <a href="https://docs.google.com/presentation/d/1M8sf5zuPgf7osR2Q7wfbkgVs7Es93rYAJTbtwiGfI7E/pub?start=false&loop=false&delayms=10000" target="_blank">
|
66 | <img src="img/about.png" alt="About Jenkins Modules">
|
67 | </a>
|
68 | </p>
|
69 |
|
70 | > Also check out the <a href="FAQs.md">FAQs</a>.
|
71 |
|
72 | # Support Modules
|
73 |
|
74 | The following [NPM] packages are designed to aid the use and adoption of `js-modules`:
|
75 |
|
76 | * [jenkins-js-builder]: See this package for details on how to create module bundles for `js-modules`.
|
77 | * [jenkins-js-test]: See this package for details on how to test modules for module bundles for `js-modules`. This package's functionality is indirectly available via [jenkins-js-builder].
|
78 |
|
79 | # Framework Libs (jenkinsci/js-libs)
|
80 |
|
81 | > __[Framework libs are located in jenkinsci/js-libs](https://github.com/jenkinsci/js-libs)__.
|
82 |
|
83 | As stated earlier, using [CommonJS] style modularity makes it possible to more easily leverage the growing set of publicly available
|
84 | [NPM]/[node.js] packages. If you want to use some really cool [NPM] package that you just found, all you need to do is follow the
|
85 | "standard" [NPM] package installation process, adding it to your "app" bundle e.g. `npm install --save cool-new-lib`.
|
86 |
|
87 | This is great, but if followed all the way, your JavaScript "app" bundles will soon become quite heavy for the browser to
|
88 | load because they will contain all JavaScript required by all the modules in the bundle.
|
89 |
|
90 | The main feature of `js-modules` is it's ability to load module bundles that can `export` / `import` modules to/from
|
91 | other modules bundles i.e. share common modules between bundles (see above slides). This means we can create `js-modules` style
|
92 | module bundles for __different versions__ of all of the major JavaScript Framework libs out there (jQuery, Bootstrap etc), making it possible for
|
93 | "app" bundles to share common Framework libs and to not have them in their "app" bundle, making them considerably lighter for
|
94 | browser load and helping to avoid the bundle bloat problem.
|
95 |
|
96 | We have already created Framework lib bundles for a number of common JavaScript libs (jQuery, Bootstrap and more).
|
97 |
|
98 | > __[Framework libs are located in jenkinsci/js-libs](https://github.com/jenkinsci/js-libs)__.
|
99 |
|
100 | [NPM]: https://www.npmjs.com/
|
101 | [CommonJS]: http://www.commonjs.org/
|
102 | [node.js]: https://nodejs.org/en/
|
103 | [Jelly]: https://wiki.jenkins-ci.org/display/JENKINS/Basic+guide+to+Jelly+usage+in+Jenkins
|
104 | [Stapler]: http://stapler.kohsuke.org/
|
105 | [jquery-detached]: https://github.com/tfennelly/jquery-detached
|
106 | [jqueryui-detached]: https://github.com/tfennelly/jqueryui-detached
|
107 | [jenkins-js-builder]: https://github.com/jenkinsci/js-builder
|
108 | [jenkins-js-test]: https://github.com/jenkinsci/js-test |
\ | No newline at end of file |