Componette

Componette

68publishers

68publishers / webpack-encore-bundle v3.0.1

Intergration of Symfony's Webpack Encore into Nette Framework

download-cloud-line composer require 68publishers/webpack-encore-bundle

Nette integration with Webpack Encore

This package allows you to use the splitEntryChunks() feature from Webpack Encore by reading an entrypoints.json file and helping you render all of the dynamic script and link tags needed.

Inspired by symfony/webpack-encore-bundle

Installation

The best way to install 68publishers/webpack-encore-bundle is using Composer:

$ composer require 68publishers/webpack-encore-bundle

the package requires integration with symfony/asset. We recommend using of our package 68publishers/asset, but you can use your own integration.

Configuration

First, register a compiler extension into DIC:

extensions:
	encore: SixtyEightPublishers\WebpackEncoreBundle\Bridge\Nette\DI\WebpackEncoreBundleExtension

Minimal Configuration

encore:
	# The path where Encore is building the assets - i.e. Encore.setOutputPath()
	output_path: %wwwDir%/public/build

You must also set the manifest path for the Asset component. If you are using 68publishers/asset, the configuration might look something like this:

asset:
	json_manifest_path: %wwwDir%/public/build/manifest.json

Multiple builds

encore:
	output_path: null # or just omit this option
	builds:
		frontend: %wwwDir%/public/frontend/build
		another: %wwwDir%/public/another/build

Default attributes

encore:
	# if using Encore.enableIntegrityHashes() and need the crossorigin attribute. Allowed values are NULL, 'anonymous' or 'use-credentials'. Default is NULL.
	crossorigin: anonymous

	# Set attributes that will be rendered on all script tags
	script_attributes:
		defer: yes
		referrerpolicy: origin

	# Set attributes that will be rendered on all link tags
	link_attributes:
		referrerpolicy: origin

HTTP Preload

All scripts and styles will be preloaded via HTTP2 header Link if the option is enabled.

encore:
	preload: yes

Entrypoints.json cache

The parsed content of the entrypoints.json file can be cached for faster loading. It is necessary to have the application integrated with symfony/console for this feature to work, as the cache must be created manually using the console command.

encore:
	cache: yes # you can use %debugMode%

To generate the cache, run the following command:

$ bin/console encore:warmup-cache

The cache file will be generated as %wwwDir%//cache/webpack_encore.cache.php.

❗ Cache must be regenerated when the entrypoints.json changes. Use the option in a production environment only and run the command within an application build.

Strict mode

By default, if we want to render tags for an entry that is not defined in the entrypoints.json, the application throws an EntryPointNotFoundException exception. You can disable this behaviour:

encore:
	strict_mode: no

Usage in Latte templates

Script and Links tags should be rendered with macros encore_js and encore_css:

{*
    {encore_js string $entryName, ?string $packageName, ?string $entrypointName, array $extraAttributes = []}
    {encore_css string $entryName, ?string $packageName, ?string $entrypointName, array $extraAttributes = []}
*}

{block js}
    {include parent}

    {encore_js 'entry1'}
    {* if you are using multiple builds *}
    {encore_js, 'entry1', null, 'frontend'}
    {* if you want to pass extra attributes *}
    {encore_js 'entry1' null, null, ['async' => true]}
{/block}

{block stylesheets}
    {include parent}

    {encore_css 'entry1'}
    {* if you are using multiple builds *}
    {encore_css, 'entry1', null, 'frontend'}
    {* if you want to pass extra attributes *}
    {encore_css 'entry1' null, null, ['hreflang' => 'en']}
{/block}

If for some reason you need manual access to individual file names, you can use the following Latte functions:

{*
    {encore_js_files(string $entryName, ?string $entrypointName): array}
    {encore_css_files(string $entryName, ?string $entrypointName): array}
    {encore_entry_exists(string $entryName, ?string $entrypointName): bool}
*}

{foreach encore_js_files('entry1') as $file}
    {var $asset = asset($file)}
{/foreach}

{foreach encore_css_files('entry1') as $file}
    {var $asset = asset($file)}
{/foreach}

{* Render tags for entry `entry2` only if the entry exists (prevents an exception throwing in a strict mode) *}
{if encore_entry_exists('entry2')}
    {encore_js 'entry2'}
{/if}

Events

If your application is integrated with symfony/event-dispatcher, you can handle the event RenderAssetTagEvent that is called when a script or link tag is generated.

namespace App\EventSubscriber;

use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use SixtyEightPublishers\WebpackEncoreBundle\Event\RenderAssetTagEvent;

final class ScriptNonceSubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents()
    {
        return [
            RenderAssetTagEvent::class => 'onRenderAssetTag',
        ];
    }

    public function onRenderAssetTag(RenderAssetTagEvent $event): void
    {
        if ($event->isScriptTag()) {
            $event->setAttribute('nonce', 'lookup nonce');
        }
    }
}

Contributing

Before opening a pull request, please check your changes using the following commands

$ make init # to pull and start all docker images

$ make cs.check
$ make stan
$ make tests.all
  • v3.0.1 v3.0.1

    Fixes

    • fixed assets preloading via HTTP2 header Link
    • fixed the header of the README

    Changes

    • Makefile is excluded from an export

    Development

    • added more tests in ApplicationResponseHandlerTest
  • v3.0.0 v3.0.0

    Version 3.0.0 🎉

    Support

    • added support for PHP versions between 7.4 and 8.2
    • added support for Latte versions between 2.5 and 3.x
    • dropped support for PHP < 7.4
    • updated version of Symfony dependencies to ^5.4 || ^6.0

    Changes

    The packages is completely refactored and a lot of features have been added!

    However, there are not much changes in the configuration. Please follow instructions in the README

    Development

    • added Dockerfile and docker-compose.yml with containers for all supported PHP versions
    • added more tests
    • added Makefile
    • added GitHub actions
    • added PHPStan
  • v2.0 v2.0

    • upgrade to Nette 3.x
  • v1.1 v1.1 - Symfony 5 & PHP 7.2+

    • dropped support for PHP 7.1
    • supported versions ^4.2 and ^5.0 for Symfony Asset Component
    • improved coding style
    • improved CI configuration
  • v1.0 v1.0 - First release

    ✔️ Nette ^2.4

Componette Componette felix@nette.org