Add Encore.configureRuntimeEnvironment() method to the public API

[Lyrkan]

This PR fixes #109 by adding an Encore.configureRuntimeEnvironment and an Encore.clearRuntimeEnvironment method to the public API.

---

Basically, until now if you tried requiring @symfony/webpack-encore without using ./node_modules/.bin/encore, it would throw an Are you trying to require index.js directly? error.

This prevented retrieving the Webpack configuration object easily, which can be needed in some cases (e.g. if you use karma-webpack).

With these changes, requiring index.js doesn't create a WebpackConfig instance anymore if the runtime environment isn't available, which removes the need of having a check at that time.

In order to deal with methods of the public API that need the WebpackConfig to be available, a Proxy of the API is exported instead of the real object. This proxy only allows calls to configureRuntimeEnvironment and clearRuntimeEnvironment if the WebpackConfig isn't initialized, or act as a passthrough if it is.

This also fixes #55 since it allows to add a try { ... } catch { ... } quite easily around all the methods of the API.

The Encore.clearRuntimeEnvironment() (that nullifies runtimeConfig and webpackConfig) was needed to write tests but since I doubt it'll really be useful outside of that case let me know if you see another way to do it.

---

Examples:

const Encore = require('@symfony/webpack-encore');
Encore
    .setOutputPath('build/')
    .setPublicPath('/')
    .addEntry('main', './src/index.ts');

If executed directly would result in the following error:

Error: Encore.setOutputPath() cannot be called yet because the runtime environment doesn't appear to be configured. Try calling Encore.configureRuntimeEnvironment() first.

Whereas the following would work:

const Encore = require('@symfony/webpack-encore');
Encore
    .configureRuntimeEnvironment('dev-server')
    .setOutputPath('build/')
    .setPublicPath('/')
    .addEntry('main', './src/index.ts');

It is also possible to pass the same options that are available using the usual CLI tool using the second argument of configureRuntimeEnvironment and camel-cased names:

const Encore = require('@symfony/webpack-encore');
Encore
    .configureRuntimeEnvironment('dev-server', {
        keepPublicPath: true,
        https: true,
    })
    .setOutputPath('build/')
    .setPublicPath('/')
    .addEntry('main', './src/index.ts');

[weaverryan]

Nice work! Sorry for the delay, but this was on my mind :). I was suspect of the Proxy at first, but it works great: even console.log() on the exported object prints as clearly as before.

[weaverryan]

It shouldn't be possible, but what about the else of this function?

[Lyrkan]

Yep, I missed that part, I added a return target[prop] just in case.

[weaverryan]

Something like:

Encore.${prop}() cannot be called yet because the runtime environment doesn't appear to be configured. Make sure you're using the encore executable or call Encore.configureRuntimeEnvironment() first if you're purposely not calling Encore directly.

A little long, but I still want to make sure people aren't making a mistake first.

[cybernet]

that message brought me here today, that was shown by phpstorm :)

[weaverryan]

no need for the else here, since you properly explode above :)

[weaverryan]

What's the purpose of the ...parameters here?

[Lyrkan]

It's needed in order to pass all the parameters to the real method: const res = target[prop](...parameters);

// Real API method
const inner = (param1, param2) => {
    console.log(`param1 = ${param1}`);
    console.log(`param2 = ${param2}`);
};

// Method returned by the proxy
const wrapper = (...parameters) => {
    inner(...parameters);
};

wrapper(1, 2);

// Output:
// param1 = 1
// param2 = 2

[weaverryan]

I think adding this everywhere is probably overkill. I think we only need to test that an exception is thrown once by using some non-safe method, and of course that no exception is thrown when using both of the safe methods. I think that's enough :)

[Lyrkan]

Exactly what I thought after copy/pasting that part for every method of the API.

I wanted a 2nd opinion before removing everything :)

[weaverryan]

This can be used to configure the Encore runtime if you're using Encore
without executing the "./node_module/.bin/encore" utility (e.g. with karma-webpack).

[weaverryan]

I'm not sure I understand this. Is there a need to continue to read the command line options? The command line options could be totally different (since there is a different executable being run).

I see that parseRuntime() looks for argv._[0] for the environment/command. Is that what you're trying to supply here? If so, I think we could set that manually - e.g. options._ = [environment]. Or, we could re-work parse-runtime.js so that the argv._[0] is actually done in encore.js and parse-runtime looked like function(command, options, cwd) {.

[Lyrkan]

I added that part to make sure that the first parameter passed to parseRuntime had the same structure than the one usually supplied by yargs, it doesn't actually keep reading the CLI options since we provide a fake process.argv (see https://github.com/yargs/yargs/blob/master/docs/api.md#api).

I did options._ = [environment] at first but switched to calling the API after realizing that yargs adds other things to the argv array that may be used later by parseRuntime (e.g.: $0)

[weaverryan]

Since this (and the logger lines) above are repeated at the top of the file, let's warp these in some function (i.e. some simple function initializeWebpackConfig() at the top of the file) that we call in both places...

[weaverryan]

Merged! This is really, really great. Thanks @Lyrkan!