Surely you are faced with the principles (albeit contradictory) about writing modules and classes in JavaScript. When I needed to write a script embedded in a web page that provides an API for the operation of a certain service, I could not find any worthy recommendations for designing such scripts.

So, here are the (rather obvious) script requirements I encountered:

• it will be embedded in the pages of third-party web applications;
• he must do his job well;
• it should load quickly;
• it should not (unpredictably) affect the operation of the web application;
• must comply with safety requirements;
• ... // much more :)

From real practice, the principles described below were born. These are not completely unique ideas, but rather a collection of best practices that I have seen in other people's solutions, such as google analytics libraries and jquery.

1. Build system

She is needed. At first it seems that you can just keep everything in one file (you can even start with this), but then it becomes clear that the assembly is necessary. Because third-party libraries are used. Because there are several options for the delivery of the script. Because the script can load resource files as needed. And you should think about it right away, even when you still keep the whole script in one file.

How to collect? Concatenation only. Because the main script should load quickly, that is, in one file.

This does not mean that you need to upload everything into one file, and hope that everything will be fine. Optional, additional features need to be loaded only when the client of the library calls the appropriate methods. But the kernel should boot up quickly, cache well, and immediately provide the client with an API.

The entire script must be wrapped in one scope. Obviously? Yes.

(function () { //     }()); 

By the way, to wrap the code in scope with Grunt, use the options banner and footer :

 concat: { injectScriptProd: { src: [...], dest: 'someScript.js', options: { banner: '(function(){\n', footer: '\n}());' } }, 

2. Switch between local and production configuration

So that it was easy to manage builds and configurations, it really helped me to get one config variable, put it in a separate configDev.js or configProd.js and have separate script assemblies. And the options for assembling for other reasons took more than two. As a result, having these simple files made it easier for me to build, code, and life. When concatenating, simply specify which files to build the script from - and the whole script file is ready.

Bad practice: to have replaceable variables throughout the entire JavaScript code of the form: <% serverUrl %>/someApi . Spoils the readability of the code, going slower. And I want to grunt watch worked really fast, is not it?

An example of our prod config file:

 var config = { server: "https://www.yourserver.com/api/", resourcesServer: "https://www.yourserver.com/cdn/", envSuffix: "Prod", globalName: "yourProjectName" }; // ,  ! 

3. How to transfer API to the outside?

There are different ways, but now we do this:

 window[config.globalName] = yourApiVar; 

This allows:

• Test several versions of the library on the page, and so that they do not interfere with each other.
• The entire script is placed in one closed scope.
• (If you suddenly need) to solve problems with compatibility. After all, we will know that the API instance is managed in the script code itself, and not in the library client code. And so we have full control over all instances.

4. “Correct” module system

I know that whatever I say here, rotten tomatoes from people who prefer a different system of modules will fly into me. Getting started.

Correctly do so:

 var module = (function () { // for each module have this structure var someInnerModuleVar; //        return { publicMethod: publicMethod }; }()); 

Why so? The answer is obvious: when you condense the code for such modules, everything will work without any libraries for modules.

5. Initializing the API

If there is at least some initialization in your library (and it is there, even if you think differently), then put it into a separate method. You can even create a separate method for initialization in each module. And then call them clearly and with a clear understanding of how it works and in what sequence.

For the first time, probably enough. Here is the structure of the resulting module:

 (function () { 'use strict'; var config = {}; var sharedState = {}; var module = (function () { var someInnerModuleVar; //  js  return { publicMethod: publicMethod, init: init }; }()); start(); }()); 

If you have ideas on how to improve the template, I will be glad to hear them. I basically wrote on java, this project is my most intense experience in javascript. Write ideas for improvement in the comments.

I also think to write about working with cookies , localStorage , db, network. Write which topics are most interesting.