Menu Developer Moovweb University

Develop Locally: Project Structure

When you first generate a JavaScript project using the Developer Dashboard, the SDK creates a top-level Moovweb Projects directory and a subdirectory named after your project. (For example, if you specified your project name as igadget, your Moovweb Projects directory will contain an igadget subdirectory.) Each time you create a project, a subdirectory is added to Moovweb Projects.

A default project includes these directories:


assets

The assets directory contains files that determine the appearance of your transformed site. Here is where you put all the images, client-side JavaScript, and CSS that you want to add to your project.

Key info

  • The JavaScript code in the assets/javascript subdirectory runs on the client. It doesn’t interact with the server-side MoovJS that transforms pages.
  • If you’re updating a Tritium project to a JavaScript one, you can simply copy-and-paste the assets directory.

build

This directory contains the auto-generated files for your compiled project for the purposes of viewing the project locally in your browser and deploying. For this reason, you should not modify any of the files here.


node_modules

This directory contains Node.js modules developed by Moovweb.

Key Notes:

  • Changes to node modules installed locally will not be reflected in the cloud. You should instead add or override any method functionality via the scripts directory, where a custom_functions.js file is provided.
  • You can install additional node modules to assist with local development using npm, which will be placed here, but only Moov node modules will be available when your project code executes in the cloud.

The directory includes these key modules written by Moovweb: moov_builder, moov_perf, moov_rewriter and moov_stdlib, with explanations below. (Full details on each individual module found on the Modules section of Moovweb’s developer documentation here.)

moov_builder

This module contains tasks that will run automatically when specific files are modified or added to your project directory. Files in your assets directory are monitored for changes, and a production-ready version of all assets will be generated and placed in a new /build/assets directory.

moov_perf

This Javascript performance module includes components that optimize your assets, such as Moovweb’s image optimizing service.

moov_rewriter

This module has core functions required by a Moovweb project to handle request and response configurations.

moov_stdlib

This module is the standard library of functions for efficiently manipulating HTML. This is the core module used by Moovweb projects to transform websites. Detailed info about moov_stdlib is available here.

When your Moovweb project runs, the functions in this module are made available via the global fns object.


tasks

Tasks provide a way for you to customize your project.

Using the three default shell scripts in the tasks directory, you can define tasks that will trigger during three general event types:

  • start: This script runs whenever you start your project. It starts Gulp, which monitors your project for changes and ensures that the deployment bundle is up to date. You define Gulp’s behavior in the moov_builder module.
  • request: This script runs every time your server encounters a request.
  • deploy: This script runs whenever you deploy your project to the Moovweb cloud. It ensures that all your assets are ready for production and bundles them into one directory.

You can edit these files to specify what tasks you want to run at each event.


tmp

This directory stores data about all requests made to your site, including HTTP logs for incoming and outgoing requests and responses, as well as environment variables available to you in MoovJS. This directory will grow over time.


scripts

This directory contains JavaScript files that define transformations in your Moovweb project. Notable scripts are detailed below.

index.js

This file serves as the “entry point” to the project, deciding what to transform and how, initially filtering by a page response’s content-type. index.js is the file that begins the sequence of script file imports using the require() function, which you’ll see throughout your generated project.

require(pathString): A global function used to import other files. It takes in a string for a path, which must be prefixed with a /, and starts from the scripts directory. If the file to be imported is a JavaScript file where a function is exported (via module.exports), this require call must subsequently be invoked.

If no match has been made for a given page response’s content-type (and thus, no decision has been made to transform it), it will pass through the transformation engine unmodified by default. We call this a perfect proxy.

perfect proxy: a technique used to pass a page through Moovweb’s transformation engine without any actual transformations.

custom_functions.js

In many cases, you may prefer to define custom functions to organize (or prevent repetition in) your code. Your generated project comes packaged with a few functions that are not core to Moovweb’s standard library moov_stdlib, but are still crucial in organizing the templated project format.

Additionally, an advanced technique you can perform within custom_functions.js is overriding the functionality provided by Moovweb’s core Node.js modules.

routes.js

This script contains routing information specifying which transformation files to run on any defined “page type.”

The file uses objects where a given page type can import a list of files. You have the option to detect pages by either URL or by an element that may be specific to that page.

The routing system is defined in a way such that the page will be transformed by the first match found in the array of “page type” objects stored in routes.mappings.

If no match is found, the page is perfect proxied. Additionally, you have the option to perfect proxy a page manually using the string value “perfectProxy” for the passthrough property, if you create a more specific page type object above another that would have otherwise matched. (The full implementation of perfect proxy handling can be found in the fns.shouldPerfectProxy() definition in custom_functions.js, which is called from index.js.)

html.js

This script contains standard functions to operate on HTML content. It also calls several functions in the moov_stdlib module. This script is executed on all HTML content transformed by the SDK.

Mobile stylesheets and client-side JavaScript are added in this file via fns.addAssets();. This file also includes lines for importing header and footer transformation files as well as for building out import system for the page-specific transformations.

json.js

The json.js file is run whenever JSON is being processed by Moovweb. This can occur when processing Ajax requests whose responses are JSON objects.

moov_main.js

This is an auto-generated file that contains the entire project’s code, which is what is used to display the project and deploy to the Moovweb cloud. Whenever you make a change to a file in your project, the Gulp task-management system ensures that moov_main.js is updated accordingly. When a request is made to your site, a new, up-to-date set of transformed code will be used.

Note that like other files auto-generated by the Moovweb SDK, you should not edit moov_main.js directly.

perf.js

This file enables the moov_perf package, and then sets up an initial configuration for optimizing the delivery of your project. Its default configuration includes a setting to decrease image file sizes using Moovweb’s image optimization software.


module.exports and Importing Files

Each new script file assigns a function to module.exports:

module.exports = function() {
  // transformation code to execute here
};

As mentioned above, we manually import script files by using the require() function. The following example will execute the code located in a file called test.js, provided that it exists in the scripts/pages/test directory. We subsequently invoke the require() call in order to execute the exported module’s function block code.

require("/pages/test/test.js")();

For specified “page types,” the project generator’s standard template comes with an easy-to-use framework for defining which files should be imported, where require() is used automatically. You can view the implementation of this under the fns.importTransformations() definition in scripts/custom_functions.js, which is called from scripts/html.js.