Design Objectives for v1.0

[divmain]

Interlock Design Objectives

This issue is meant to track high-level objectives for Interlock v1.0. It is subject to revision as the work progresses.

First-class support for large teams

• [x] each module has a unique, canonical ID that is independent of build time or machine, and dependent on module path, namespace, contents (version), and dependencies
• [x] modules that have already been downloaded once should never be downloaded again, unless bundled with a module that has not already been downloaded
• [x] module-to-URL resolution is easily overridable (should be able to modify the module-request mechanism altogether). (#28)
• [x] simple hooks are provided for CDN integration at build-time
• [x] simple mechanism is provided to import and consume pre-compiled JavaScript from application code (#29)

  Run-time performance

• [x] code splitting
• [ ] asynchronous loading of split files (#30)
• [x] JS applications that have been compiled separately can both execute in the same browser environment without special configuration
• [x] applications that depend on shared resources should require minimal configuration for those dependencies, and zero knowledge of each other
• [x] under HTTP/1 bundle profile, ALL modules are bundled into the same JS EXCEPT where split points are defined
• [x] under HTTP/2 bundle profile, NO modules are bundled into the same JS EXCEPT where split points are defined (all other files are emitted as individual files) (#31)
• [ ] hybrid runtime loader can determine which JS bundles to load based on HTTP/2 feature availability (#32)
• [ ] loader can leverage swappable caching mechanisms where browser support is available, including: (#28)
  • [x] Local Storage (#33)
  • [ ] IndexedDB (#34)
  • [ ] conditional loading from CDN (#35)

    Build-time performance

• [x] completely async/non-blocking build process
  • [x] stream- and promise-based implementation
  • [x] remove all synchronous fs calls - async Pluggables only
• [x] use AST as end-to-end intermediate data-structure during build process
  • Note: Webpack already parses JS into AST three times during build, which is a very expensive operation. JS is also parsed into AST by ESLint, Babel, and other tools.

    Friendliness to application developers

• [x] built-in, first-class support for ES2015 and JSX
• [x] support for CommonJS, AMD, and ES2015 modules
• [x] first-class support for Babel plugins (#36)
• [x] workflows optimized for three use cases / personas:
  • [x] new/mid-tier dev, a browserify-like experience; one command line, no config necessary, just inputs and outputs (#18, #37)
  • [x] mid-tier/advanced dev, drive compilation through well-documented and familiar config
  • [x] advanced dev, composability: support custom pipelines that are separate from built-in interlock compile method (#18, #38)
• [ ] CLI tool with flags supporting the common 80% of use cases (#18)

  Powerful extensibility

• [x] plugin system is well documented
  • [x] documentation is automatically generated
  • [x] freshness and correctness of documentation is enforced by CI
• [x] plugin system supports multiple concurrent compilations
• [x] plugin system does not sacrifice either the readiblity or the "pure functional" architecture of the code base
• [x] extension points are discoverable through documentation and through code
• [x] for each extensible piece of code, there are be pre-defined ways that the output can be extended (i.e. different extension points do not have different interfaces)
  • [ ] transform-input
  • [x] override
  • [x] transform
• [x] multiple types of asynchronicity are supported (promises, streams, and synchronous code)
• [x] where practical, extension points work with AST all the way through: "Hello Babel-, ESlint-, and Esprima-plugin writers; you are welcome here."
• [ ] official plugins
  • [ ] customizable sourcemapping URL plugin (#39)
  • [x] handlebars loader plugin
  • [x] json loader plugin

    Parity with other tools

• [x] partial/cached compile and watch mechanism
• [x] fast and straightforward dev server (#42)
• [ ] hot module reloading mechanism (#43)
• [x] non-JS assets are supported both as JavaScript and as non-JS via alternate pipelines (#44)
• [x] source-maps
  • [x] source-included
  • [x] source-separate
• [x] validation for config (#19)
• [ ] helpful error messages (#45)

  Tests

• [ ] 100% test coverage (#46)
• [ ] two or three end-to-end integration tests (#47)
• [ ] test to ensure that example app always works (#48)

  Documentation

• [x] website (#49)
• [ ] getting started tutorial (#50)
• [ ] 4-10 "recipes" for common use cases (#51)
• [x] API documentation (#52)
• [x] extension documentation (#53)

  General philosophy

• embrace the Zen of Python and in particular:
  • There should be one-- and preferably only one --obvious way to do it.
  • Explicit is better than implicit.
  • Simple is better than complex. Complex is better than complicated.
  • Readability counts.
• only diverge from functional patterns as a special case
• adopt AST as the "right" intermediate data-structure for JavaScript
• one more time, because it is important... "readability counts"

[baer]

Additional Item: Not sure if ti belongs here or as a separate issue since it's a bit more granular than most of these but I'd say that input validation (and helpful error messages) on the base Interlock class has strong enough developer ergonomics implications that it should be a 1.0 feature.

[baer]

Modification: In my experience, an example is worth 1000 tutorials. Gulp did a really good job with this by providing "recipes" in their documentation section for a lot of common use cases. With enough comments this can take the place of writing and maintaining the above 4-5 tutorials.

https://github.com/gulpjs/gulp/tree/master/docs/recipes

[baer]

Additional Item: Some users may not want to use source maps as a developer only tool rather than distributing them with the code. In order to do this, you need a customizable sourcemapping URL. It's a simple change to take this as an option but I'd probably consider this a 1.0 feature.

https://github.com/interlockjs/interlock/blob/master/lib/compile/index.js#L98-L102

[baer]

Modification: Rename ES6/ES7 references to ES2015/ES2016. TC39 has been pushing really hard to have the JS community think of JS as a living spec and have committed to an annual release train for the language. As a part of that effort ES6/ES7 are now ES2015 and ES2016 respectively.

https://esdiscuss.org/topic/javascript-2015

[baer]

Removed Item: Since the loading of modules is so mission critical it might be a little ambitious to commit to 3 caching backends and possibly to commit to caching at all for a 1.0 release.

[baer]

Removed Item: Unless HTTP2 support will inform design decisions (it may) it may not need to be a part of 1.0. I don't even think nginx has production HTTP2 modules yet so I don't think this will alienate anybody.

[baer]

Additional Item: CLI Support

[divmain]

@baer.

• input validation: agreed
• recipes vs tutorials: very good point, agreed
• custom sourcemap URLs: this is super simple with the new plugin system - I plan to have a set of default plugins, and this functionality can be incorporated there
• ES2015/ES2016: I didn't realize - I'll make this change
• caching backends: the mechanism for integrating these caching backends should be included in the initial release; at that point, implementing the things will be trivial, so no reason not to include them
• HTTP/2 build profile: normally I would agree with you in this regard. However, proper support for HTTP/2 paradigm is a significant differentiator for Interlock when compared to webpack. So I'd like to keep it in, even if it isn't technically necessary for an MVP.
• CLI support: I hinted about it when talking about the new/mid-tier dev experience, but I'll call it out more specifically.

Thanks!

[baer]

I'm happy to keep adding tests and if you'd like, I can take the input validation in the Interlock class. I think you're right about pulling in joi over validate.js. If there are others you'd like help with you can use issues + github's help-wanted tag :smiley:

[divmain]

Created tickets for remaining items.