broccolijs/broccolijs.github.io

Website code. Master branch contains generated html, code contains the code

broccolijs.github.io's Issues

Rest of the guide?

The Getting Started guide says:

For this example, we’re going to keep it relatively simple and just build Sass into CSS and Coffeescript into Javascript.

But there are no pages about this; the content ends after the end of the first page.

Additionally, it is missing some content—the very next sentence reads:

We’re also going to assume your project structure looks like:

But there is nothing there; it jumps right into describing the package.json file.

Site is down

build --overwrite error

The problem

I've been following the guide on the getting started page and I noticed an error.
(I'm sorry if this isn't the correct repo, but it seems like it would be the right place)

The page says the following:

To run a build, run yarn build (if you added the script) or broccoli build --overwrite (note: without --overwrite the contents of the output directory dist will NOT be overwritten and produce an error).

I tried running npx broccoli build --overwrite yarn broccoli build --overwrite and yarn build --overwrite yet they all have approximately this output:

yarn run v1.17.3
warning package.json: No license field
$ broccoli build --overwrite
error: unknown option `--overwrite'
error Command failed with exit code 1.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.

My hunch is that this command was deprecated, and the guide hasn't been updated yet.

Solutions

Here's a list of different independent possible solutions.

• Update the website to reflect above-mentioned depreciation/removal
• Add the feature back to the code
• Repair the bug

My personal opinion is that the argument should be ignored, for compatibility, and should be removed from the doc.
(My reason the tsc compilation command automatically replaces any file effected by the source change. I really like this approach.)

Note: I had previously opened the issue on this repository,
but I did a bit more digging, and this may be the one to propose the issue too.

I'll close the issue on the other one for now, at least.

Broccoli Plugin Authorship Docs

List of use cases for the different types of plugin you might want to build...

We want people to think about a broccoli plugin in the right way.
It's kind of like a component.
Does not break encapsulation.
Has defined inputs and output.
It should be isolated.
Errors.
Debugging, broccoli test helper

Common questions

Encapsulation, what you get/write
Why/how do I use multiple inputNodes?
How do you go from naive plugin, to cached and/or persisted
What hooks need to be implemented? Build and constructor
What do I export? How do I compose/inherit?

What do I export? How do I compose/inherit?

Use cases: building a pipeline, extending a plugin (authorship)
Explain why with below:

// MyPlugin.js
module.exports = myPlugin(...params) => {
    return new MyPlugin(...params);
}
module.exports.Plugin = MyPlugin;

// consumption
const oliPlugin = require('oli-plugin');
oliPlugin(previousNode);

// extension
const { Plugin: OliPlugin } = require('oli-plugin');
class OtherPlugin extends OliPlugin{}

What hooks need to be implemented? Build and constructor

Constructor: https://github.com/broccolijs/broccoli-plugin#new-plugininputnodes-options
Build:

• when is it invoked? When broccoli needs the output of your plugin, it will ensure that your inputs are ready.
• What are you given?
• inputPaths resolved with absolute paths for input files
• do not write to inputs
• use paths relative to inputPaths
• respect node resolution, don't use cwd()
• return a promise or nothing
• only 1 plugin is built at any given time