Statistics
18896
30
1
90d
Badges
Dependencies

Oops/WebpackNetteAdapter

Build Status Code Coverage Downloads this Month Latest stable

WebpackNetteAdapter is a tool that helps integrate your Nette Framework application with assets built via Webpack.

Installation and requirements

$ composer require oops/webpack-nette-adapter

Oops/WebpackNetteAdapter requires PHP >= 7.2.

Usage

Register the extension in your config file, and configure it. The two build options are mandatory:

extensions:
    webpack: Oops\WebpackNetteAdapter\DI\WebpackExtension(%debugMode%, %consoleMode%)

webpack:
    build:
        directory: %wwwDir%/dist
        publicPath: dist/

Now you can use the {webpack} macro in your templates. It automatically expands the provided asset name to the full path as configured:

<script src="{webpack app.js}"></script>

webpack-dev-server integration

You might want to use the Webpack's dev server to facilitate the development of client-side assets. But maybe once you're done with the client-side, you would like to build the back-end without having to start up the dev server.

WebpackNetteAdapter effectively solves this problem: it automatically serves assets from the dev server if available (i.e. it responds within a specified timeout), and falls back to the build directory otherwise. All you have to do is configure the dev server URL. The dev server is enabled automatically in debug mode; you can override this setting via enabled option:

webpack:
    devServer:
        enabled: %debugMode% # default
        url: http://localhost:3000
        timeout: 0.1 # (seconds) default

Ignored assets

You can also configure a set of asset names that should be ignored (i.e. resolved to an empty data URI) if the dev-server is available. This can be helpful e.g. if you use style-loader in development which does not emit any CSS files.

webpack:
    devServer:
        ignoredAssets:
            - main.css

Public URL (e.g. Docker usage)

Dev-server might have different URLs for different access points. For example, when running in Docker Compose setup, the Nette application accesses it via the internal Docker network, while you access it in the browser via the exposed port. For this, you can set up a different publicUrl.

webpack:
    devServer:
        url: http://webpack-dev-server:3000 # URL over internal Docker network
        publicUrl: http://localhost:3030 # exposed port from the dev-server container

Asset resolvers and manifest file

You might want to include the Webpack's asset hash in its file name for assets caching (and automatic cache busting in new releases) in the user agent. But how do you reference the asset files in your code if their names are dynamic?

WebpackNetteAdapter comes to the rescue. You can employ the webpack-manifest-plugin or some similar plugin to produce a manifest file, and then configure the adapter to use it:

webpack:
    manifest:
        name: manifest.json

This way, you can keep using the original asset names, and they get expanded automatically following the resolutions from the manifest file.

WebpackNetteAdapter automatically optimizes this in production environment by loading the manifest file in compile time.

Debugger

In development environment, WebpackNetteAdapter registers its own debug bar panel into Tracy, giving you the overview of

  • what assets have been resolved and how;
  • the path from where the assets are served;
  • whether the dev server is enabled and available.

Debug bar panel

  • 1.3.1 1.3.1

    • 🐞 Fixed BuildDirectoryProvider pointing to public URL of dev server instead of the internal one if a public URL is configured. (#16)
  • 1.3.0 1.3.0

    • You can now configure the DevServer with a different internal and public URL for easier use in environments such as a Docker Compose network. (#13, thanks @martinjinda!)
  • 1.2.0 1.2.0

    • 🔧 Minimum required version of PHP is now 7.2, and up to 7.4 is supported.
    • 🐞 AssetLocator trims extra leading slashes that might force the browser to treat the asset name as a protocol-less absolute URL.
    • 🐞 WebpackNetteAdapter no longer tries to pre-load assets manifest when running the application in CLI, preventing failures when the assets are not built. If you use CLI to warmup DI container cache, you can bypass this behaviour by setting the OOPS_WEBPACK_OPTIMIZE_MANIFEST env variable to a truthy value.
    • You can configure AssetLocator to ignore certain asset names when the dev-server is available. Ignored assets are resolved to an empty Data URI. This is particularly helpful if you use style-loader in development which does not emit any CSS files.
  • 1.1.0 1.1.0

    • This release brings compatibility with Nette 3.0 🎉 (as well as Nette 2.4 at the same time). Also, PHP version requirement has been raised to 7.1.
    • Some hidden hard dependencies on Nette packages (such as nette/application or nette/http) have been removed, so that WebpackNetteAdapter can be employed even in less traditional development stacks.
    • The timeout of DevServer's heartbeat check is now configurable, defaulting to the current value of 100 ms.

Is this addon outdated? Did you find an issue? Please report it.

Componette Componette admin@componette.com