Proposal for build blades command

Although https://github.com/BladeRunnerJS/brjs/issues/338 has been raised to allow multi-page web-apps, this story doesn't cover the need for multi-page apps to have quicker page-load times than what is acceptable in SPAs, nor does it cover the common use case to allow people to integrate page content containing components developed within BRJS with a pre-existing web-site.

This proposal seeks to solve all issues:

1. To allow blades and libraries developed within BladeRunnerJS to be easily used within a pre-existing multi-page site.
2. To allow multi-page BRJS apps (via #338) to use the same infrastructure to reduce page download times.

The requirements for this proposal are as follows:

• Developers would like the ability to build the various blades within an application into a set of flat files that can be pulled in to a web-site or CMS by inserting the appropriate <script/> tags into each page of the site.
• Each page should only load the blades and libraries necessary for that page to reduce page-load time.
• We shouldn't create unique bundles for each page since that would prevent caching, increasing page-load time.
• BladeRunnerJS should not need to know about the pages within the external web-site, preventing the need to keep both systems in sync.
• In development it should be possible for the developer to configure their local copy of the web-site to retrieve the built bundles directly against the BRJS instance the developer is developing against.
• In production it should be possible to run an build-blades command that produces static files that can be served with a publicly facing web-server that pages can load from.
• Each page should be able to use <script/> tags to define the blades or bladesets they want loaded, and this should cause all transitive dependencies to be loaded without introducing any additional network latency for transitive dependency discovery.
• We should ideally not need to introduce any new concepts to implement this feature as BRJS requires quite a few concepts to understand it already.

The proposed solution is for a build-blades command plug-in and content plug-in that allow a consistent set of URLs to be used for loading blades and bladesets:

• /v/<version>/blade/<blade-name> (a JavaScript descriptor that loads all transitive dependencies needed for the given blade)
• /v/<version>/bladeset/<bladeset-name> (a JavaScript descriptor that loads all transitive dependencies needed for the given bladeset)
• /v/<version>/bundles/blade/<blade-name>/<content-path> (blade bundle content)
• /v/<version>/bundles/bladeset/<bladeset-name>/<content-path> (bladeset bundle content)
• /v/<version>/bundles/library/<library-name>/<content-path> (library bundle content)

These URLs would be used as follows:

1. The first two URLs would be placed within a pages <script/> tags based on the blades a page needs to access.
2. The descriptor scripts would contain commands that cause all the transitive dependencies, regardless of asset-type (e.g. JavaScript, HTML, CSS & XML) to be loaded by the client.
3. Bundles that have already been loaded due to a previous JavaScript descriptor for another blade or bladeset will be ignored.
4. Once all of the blades dependencies have been loaded then some client code will be informed so it can begin to make use of those blades.

Although adding <script/> tags to a page for all the blades that are in use is appealing due to it's simplicity, it's possible instead that we will need to use a single script tag plus a code-segment, so we can know when everything has been loaded.

For example, to load the 'default' bladeset, and blades 'b1' and 'b4' from the 'extra-stuff' bladeset, we might add this to our page:

<script src="http://the-server/app/built-blades"></script>
<script>
    loadBlades(['default', 'extra-stuff/b1', 'extra-stuff/b4'], function() {
        // start making use of the blades we've loaded here...
    });
</script>

To allow the same page code to be used in both development and production the developer could override where the-server points to on their local machine, so that it points to localhost.