Skip to content

Latest commit

 

History

History
285 lines (256 loc) · 8.79 KB

spec.md

File metadata and controls

285 lines (256 loc) · 8.79 KB
Raw

asset-builder Manifest Spec 1.0

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC2119.

JSON Serialization

Examples

Following is a simple, minimal example of a manifest.json:

{
  "dependencies": {
    "app.js": {
      "files": [
        "scripts/**/*",
        "scripts/main.js"
      ],
      "main": true
    },
    "main.css": {
      "files": [
        "styles/main.less"
      ],
      "main": true
    },
    "modernizr.js": {
      "bower": ["modernizr"]
    }
  }
}

A more extensive manifest.json follows.

{
  "dependencies": {
    "app.js": {
      "files": [
        "scripts/services/**/*.js",
        "scripts/controllers/**/*.js",
        "scripts/directives/**/*.js",
        "scripts/main.js"
      ],
      "vendor": [
        "../../plugins/example-plugin/assets/plugin.js"
      ],
      "main": true
    },
    "main.css": {
      "files": "styles/main.less",
      "vendor": [
        "../../plugins/example-plugin/assets/style.css"
      ],
      "main": true
    },
    "homepage.js": {
      "files": [
        "custom-dir/homepage.js"
      ],
      "external": true,
      "bower": ["slick-carousel"]
    },
    "jquery.js": {
      "bower": ["jquery"]
    },
    "modernizr.js": {
      "bower": ["modernizr"]
    },
    "fonts": {
      "files": ["fonts/**/*"]
    },
    "images": {
      "files": ["images/**/*"]
    }
  },
  "paths": {
    "source": "assets/",
    "dist": "build/"
  },
  "config": {
    "devUrl": "example.dev"
  }
}
  • In addition to containing more dependencies, the example contains optional properties such as paths.
  • The directory where the compiled files are output has been changed to build/.
  • The app.js dependency is pulling in a vendor file from a directory outside the project directory.
  • The homepage.js dependency has specified an external as true. This means it will expect to find custom-dir/homepage.js and not assets/custom-dir/homepage.js.
  • homepage.js has also specified that it requires slick-carousel as a bower dependency. In this case slick-carousel will be excluded from being automatically included in app.js and will be included in homepage.js.
  • main.css in this case only has one file, so its files property can optionally be defined as a string.
  • A fonts and images dependency has been specified: if you do not include these properties explicitly they will be automatically added for you.
  • A path inside the files property such as scripts/main.js will be transformed to assets/scripts/main.js if your manifest's paths.source is assets/ and the dependency's external property is not set to true. The vendor property paths are relative to your project root. If you are using gulp, this is typically where your gulpfile.js is located.

Defaults

{
  "dependencies": {
    "fonts": {
      "files": ["fonts/**/*"]
    },
    "images": {
      "files": ["images/**/*"]
    }
  },
  "paths": {
    "source": "assets/",
    "dist": "dist/"
  }
}

manifest.json Serialization

Property Value Description
dependencies Dependencies Defines project’s output files by listing the inputs as Dependency objects. A manifest MUST contain a "dependencies" property.
paths Paths Defines a project’s input and output locations. A manifest MAY contain a "paths" property.
config JSON [RFC4627] Object An object containing arbitrary configuration values as properties. This is mainly just a convenience so you can feed static values to your build process. A manifest MAY contain a "config" property.

Dependencies Serialization

Property Value Description
{{NAME}}.js Dependency Defines project’s output files by listing the inputs as Dependency objects. A manifest MAY contain one or more JS Dependencies.
{{NAME}}.css Dependency Defines project’s output files by listing the inputs as Dependency objects. A manifest MAY contain one or more CSS Dependencies.
fonts Dependency Defines a project’s fonts. If this is not explicitly defined by the user it will be automatically defined with a files property as 'fonts/**/*'. A Dependencies MAY contain a "fonts" property.
images Dependency Defines a project’s images. If this is not explicitly defined by the user it will be automatically defined with a files property as 'images/**/*'. A Dependencies MAY contain an "images" property.

Dependency Serialization

Property Value Description
files JSON [RFC4627] Array of Strings OR String Describes a list of file paths to local project files in glob format. A Dependency MAY contain a "files" property. These are generally first-party project files. You can run all of your linters and styleguide checkers on these files. By default `path.source` will be prepended to each glob in this collection. To turn this behavior off, one sets the `external` property to true.
vendor JSON [RFC4627] Array of Strings OR String Describes a list of file paths to vendored project files in glob format. A Dependency MAY contain a "vendor" property. Generally you should treat these dependencies as third-party code. That means you should not run linters and styleguide checkers on these files.
bower JSON [RFC4627] Array of Strings OR String Describes a list of bower package names to be included in that dependency. A Dependency MAY have a "bower" property.
main boolean Describes whether or not all of the bower dependencies will automatically be included in this Dependency. A Dependency MAY have a "main" property.
external boolean Describes whether or not the source (`path.source`) directory will be prepended to each glob in the "files" property. A Dependency MAY have an "external" property. The external property should be considered `false` by default.

Paths Serialization

Property Value Description
source JSON [RFC4627] String Describes the base location of a project’s asset folder. This will be prepended to all Dependency "file" globs unless `external: true` is specified. The "source" property MUST have a trailing slash. Paths MAY have a "source" property.
dist JSON [RFC4627] String Describes the base location of a project’s target build folder. Paths MAY have a "dist" property.

Footnotes

See Also

Globs

  • man sh
  • man bash (Search for "Pattern Matching")
  • man 3 fnmatch
  • man 5 gitignore
  • minimatch

References

[RFC4627] Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” July 2006.