1 - Introduction

Many JavaScript frameworks use some kind of development environment, such as grunt, gulp, webpack or rollup. The reason for this is that it quickly becomes too difficult and time consuming to manage multiple source files and assets; there are several important optimizations required for deploying top-of-class web experiences that are best left to automated scripts.

SproutCore provides its own development environment, called build tools, or BT for short.

BT provides the following and more:

• Automatically scans your source code and builds a manifest of how your code should be built into a final project. This ensures that your JavaScript and CSS always load in the proper order.
• Run stylesheets through the Compass CSS Authoring Framework for simple and clean CSS.
• Proxies XHR requests to avoid same-origin policy restrictions while developing.
• Applies localization rules to automatically build different language variations of your project.
• Inserts cache-friendly URLs on build for any assets (such as images) that you may want to load.
• Builds your JavaScript files and stylesheets into a single JavaScript and a single CSS file and minifies the contents of each. This makes your deployed app load much faster since multiple smaller requests are slower for the clients.

For a list of the available commands, type sproutcore on the command line after installing the SproutCore gem:

$ sproutcore

  Usage: sproutcore [options] [command]

  Options:

    -V, --version       output the version number
    -h, --help          output usage information

  Commands:

    install [git-repo]  Install a repository, such as a framework
    serve               Start the development server
    build [app1]        Start the building process of one or more apps
    gen <name>          Generate project structure or parts of it
    init <name> [path]  Generate new project structure and app with the same name and an optional path
    help [cmd]          display help for [cmd]

2 - Generating a New SproutCore Project: sproutcore init

To create a new basic SproutCore project simply use sproutcore init or its short form equivalent, sc-init, and supply a project name and optional path where to create it. If you don't supply the path parameter, the project will be created in a directory of the same name in the current directory. By default an application of the same name will be created in the projects app folder. Any additional app can be created using the gen command:

$ sproutcore init MediaTools
  Your project has been successfully created!
$ cd MediaTools
$ sproutcore gen VideoEditor

3 - Generating Additional SproutCore Files: sproutcore gen

The command sproutcore init creates a few default files for you that form a typical starting point for a new project, but you will soon need other files and this is where the command sproutcore gen can come in.

3.1 - sproutcore gen app AppName

When called from within a project, adds an app to the project with the namespace AppName.

4 - Configuring SproutCore Applications: sc_config

The operations of the build tools are configured via the project, framework and app sc_config files. If you used the previous commands, you will find a sc_config within your root project directory and a sc_config in each of your app directories.

Before we look at the contents of the configuration files, it is important to realize that the BT essentially functions in two modes: a 'debug' mode and a 'build' mode. The debug mode is the mode where the BT is used to provide a dev server. The build mode is the mode when you use the BT to generate HTML, CSS and JS files on disk.

We start by looking at the sc_config file in the application directory root. The default file generated by the BT looks like this:

var TodosOne = BT.AppBuilder.create({
  name: 'TodosOne',
  path: dirname(),
  title: 'TodosOne',
  frameworks: [],
  languages: ['en'],
});

The following list describes the most common properties.

4.1 - name: 'TodosOne'

The name of the project as it should be recognized by the BT. Any files created during the build phase will carry this name, as well as the base url in the dev server.

4.2 - path: dirname()

By default dirname() will fill in the current path of the sc_config file. There can be reasons to have the BT load a different path for this app.

4.3 - title: 'TodosOne'

The title you want the app to have in the generated HTML.

4.4 - frameworks: []

The list of frameworks your app depends on. A default set of SproutCore frameworks will be included by default. The BT will look for the frameworks in the projects frameworks folder. Using the name of the framework folder is usually sufficient. In case you want to be selective, and only use selected frameworks from a frameworks bundle (such as SproutCore), use : to seperate the framework names. To use the experimental select views framework for example, you would include 'sproutcore:experimental:select_ext' in the frameworks list.

4.5 - languages: []

List of languages this app will support.

4.6 - language: {String}

Which language the BT will use when serving the app through the dev server.

4.7 - theme: {String}

The theme your application will use. The default is sproutcore:aki'`.

4.8 - buildNumber: ''

By default, the build project assets will get cache friendly paths containing a unique build number. This is necessary to ensure that the files are properly cached, but you can specify a custom build number with this setting.

4.9 - combineScripts: {Boolean}

Whether the BT should combine the scripts in a single file. By default, this setting is false in debug mode, and true in build mode. Setting combineScripts to false will prevent the combining in build mode, which may be useful for debugging purposes.

4.10 - combineStylesheets: {Boolean}

By default, the BT in build mode combines all the CSS files into a single file. Setting combineStylesheets to false will prevent this from happening, which may be useful for debugging purposes.

4.11 - minifyScripts: {Boolean}

By default, the BT in build mode will minify all scripts. Setting minifyScripts to false will prevent this from happening, which may be useful for debugging purposes.

4.12 - minifyStylesheets: {Boolean}

By default, the BT in build mode will minify all stylesheets. Setting minifyStylesheets to false will prevent this from happening, which may be useful for debugging purposes.

4.13 - contentForPageStyles: {String}

Insert here any HTML which should be inserted together with the styles.

4.14 - contentForPageJavaScript: {String}

Use this to include script tags to third party scripts not to be included in the HTML, CSS and JS files generated by the BT.

5 - Developing with SproutCore: sproutcore serve

So that you can view and test your code in action immediately, the build tools also provide a local server and proxy. As was mentioned in Getting Started, you run the server by changing to your project's directory and running sproutcore serve. The server will monitor your files for changes and re-build them when they do change. To keep the process fast and to allow you to debug your code while developing, the individual files aren't packed or minified in debug mode. When your server is running, you can access your apps at http://localhost:4020 or a specific app at http://localhost:4020/app_name.

The server also includes a proxy that is configurable within the project's Buildfile. Without a proxy, XHR requests will fail since the origin of your test page, http://localhost:4020 will not match the origin of your backend server (ex. https://my-private-api.com:8080) and the browser will consequently reject the request. Therefore, if you want to load data from your backend from a URL like https://my-private-api.com:8080/users/3, your XHR request must be to /users/3 and you will use the SproutCore server to proxy the request across.

Here are some examples configuring the SproutCore server proxy:

// filename: my_project/sc_config
BT.serverConfig = {
  proxies: [
    // Proxy all requests for '/news' to 'http://news.com/news'.
    {
      prefix: '/news',   // set a prefix here for the development server
      host: 'news.com', // to which host should the request be forwarded
      port: 80, // on which port is the host listening?
      logRequests: false, // show the requests in the terminal?
      proxyPrefix: '/news' // replace the prefix set above with this
    },
    // Proxy all requests for '/session' to 'https://session-server.net/session'.
    {
      prefix: '/session',   // set a prefix here for the development server
      host: 'session-server.net', // to which host should the request be forwarded
      port: 443, // on which port is the host listening?
      logRequests: false, // show the requests in the terminal?
      proxyPrefix: '/session' // replace the prefix set above with this
      secure: true,
    },
      // Proxy all requests not matching anything in the BT to 'https://session-server.net/session'.
    {
      prefix: '/',   // set a prefix here for the development server
      host: 'session-server.net', // to which host should the request be forwarded
      port: 443, // on which port is the host listening?
      logRequests: false, // show the requests in the terminal?
      proxyPrefix: '/session' // replace the prefix set above with this
      secure: true,
    },
  ]

}

6 - Building a SproutCore Application: sproutcore build

Finally, when your application is ready to be deployed to a real server, you will do a production build and move the files across to be hosted. Depending on the options you set in your sc_config file, this will generate some variant of static deployable and cache-able content.

Ex. Building all apps and required frameworks within a project.

$ sproutcore build

Ex. Building a specific app within a project, including it's required frameworks.

$ sproutcore build my_app

We take one last look at the sc_config file in your project directory. You will notice the familiar sc_require() call in the top of the file. The BT will not include any app in your project unless you specifically indicate you want to include it. If you want to temporarily remove an app from the project, simply comment out the sc_require line from the projects sc_config file.

Here are some useful settings:

6.1 - port: {Number}

Set this to the port you want to run the dev server on. The default value is 4020. You can temporarily override this setting on the command line:

sproutcore serve -p 4021

6.2 - localOnly: {Boolean}

By default, the dev server will only be available on your computers special localhost domain, and therefore hidden for the rest of the network you might be in. If you want to be able to test your application from a different computer, set the localOnly value to false and restart the dev server. This will make the dev server listen on the defined port on all network interfaces.

sc_require('apps/TodosOne/sc_config')

/*
Please don't remove the following server configuration, as the build tools use it to
determine the root of your project.
 */

BT.serverConfig = {

  /**
    The port on which the development server should run

    @property
    @type Number
    @default 4020
  */
  port: 4020,

  /**
    Set it to false to allow access from the network.

    @property
    @type Boolean
    @default true
  */
  localOnly: true,

  /**
    A JSON file to use to store build numbers.
    You must define this property to enable build number support.

    Example:

        buildNumberPath: 'build_number.json',

    @property
    @type String
    @default null
  */
  buildNumberPath: null,

  /**
    Define this property if you need one or more proxies.
    If you do a request from your app (file or XHR) which doesn't match anything the BT provide,
    the request will be run past the proxies in the order you define them here.
    You can use the prefix to filter which requests will be forwarded to where.
    In the proxied request the prefix you define will be replaced by the proxyPrefix.
    The example shows how to set up a catch-all proxy, in this case to CouchDB.
    You can set as many proxies as you want, as long as they don't share a prefix.

    Example:

        proxies: [
          {
            prefix: '/',   // set a prefix here for the development server
            host: 'localhost', // to which host should the request be forwarded
            port: 5984, // on which port is the host listening?
            logRequests: false, // show the requests in the terminal?
            proxyPrefix: '/' // replace the prefix set above with this
          }
        ]

    @property
    @type Array
    @default null
  */
  proxies: null

}

7 - Changelog

• February 27, 2012: initial version by Tyler Keating
• February 28, 2012: added some documentation on sc-server & sc-build by Tyler Keating
• December 17, 2012: added note about changing proxy settings by Mike Atkins
• July 14, 2013: converted to Markdown format for DocPad guides by Topher Fangio
• January 17, 2019: Updated to document the NodeJS based BT by Maurits Lamers

Chapters

1. Introduction

2. Generating a New SproutCore Project: sproutcore init

3. Generating Additional SproutCore Files: sproutcore gen

   • sproutcore gen app AppName

4. Configuring SproutCore Applications: sc_config

   • name: 'TodosOne'

   • path: dirname()

   • title: 'TodosOne'

   • frameworks: []

   • languages: []

   • language: {String}

   • theme: {String}

   • buildNumber: ''

   • combineScripts: {Boolean}

   • combineStylesheets: {Boolean}

   • minifyScripts: {Boolean}

   • minifyStylesheets: {Boolean}

   • contentForPageStyles: {String}

   • contentForPageJavaScript: {String}

5. Developing with SproutCore: sproutcore serve

6. Building a SproutCore Application: sproutcore build

   • port: {Number}

   • localOnly: {Boolean}

7. Changelog