包简介

Use Webpack Encore in TYPO3 Context

README 文档

README

TYPO3 integration with Webpack Encore!

This extension 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.

composer require ssch/typo3-encore

How to use

First of all install Webpack Encore as stated in the documentation. You should really be able to use all of the things described in the documentation. Like Sass-Loader, Vue-Loader etc. These things are completely independent from this little extension.

You can also use the enableVersioning() of files (mostly used only in production context). You can also use the enableIntegrityHashes(). This is taking into account if the files are included.

Define your entry path(s) and the output path (usually your Resource/Public/ folder in your Package extension) in the webpack.config.js
Afterwards set the two TypoScript constants to point to the manifest.json and the entrypoints.json located in the configured output folder

plugin.tx_typo3encore {
    settings {
        entrypointJsonPath = EXT:typo3_encore/Resources/Public/entrypoints.json
        manifestJsonPath = EXT:typo3_encore/Resources/Public/manifest.json
    }
}

In your Page templates/layout you can then use the ViewHelpers to integrate the CSS- and JS-Files in your website

<html
    xmlns:f="http://typo3.org/ns/TYPO3/CMS/Fluid/ViewHelpers"
    xmlns:encore="http://typo3.org/ns/Ssch/Typo3Encore/ViewHelpers"
    data-namespace-typo3-fluid="true"
>

<encore:renderWebpackLinkTags entryName="app"/>
<encore:renderWebpackScriptTags entryName="app"/>

</html>

If you have defined multiple entries you can define the desired entryName in the ViewHelpers

<html
    xmlns:f="http://typo3.org/ns/TYPO3/CMS/Fluid/ViewHelpers"
    xmlns:encore="http://typo3.org/ns/Ssch/Typo3Encore/ViewHelpers"
    data-namespace-typo3-fluid="true"
>

<encore:renderWebpackLinkTags entryName="secondEntryName"/>
<encore:renderWebpackScriptTags entryName="secondEntryName"/>

</html>

Alternatively you can also include the files via TypoScript

page.includeCSS {
    # Pattern PKG:typo3_encore:entryName
    app = PKG:typo3_encore:app
    # If you want to ensure that this file is loaded first uncomment the next line
    # app.forceOnTop = 1
}

page.includeJS {
    # Pattern PKG:typo3_encore:entryName
    app = PKG:typo3_encore:app
    # If you want to ensure that this file is loaded first uncomment the next line
    # app.forceOnTop = 1
}

page.includeJSFooter {
    # Pattern PKG:typo3_encore:entryName
    app = PKG:typo3_encore:app
}

Note the prefix PKG:typo3_encore: This is important in order to render the files correctly. You can then use all other known settings to include your files.

You don´t have to care about including it only once. This will not happen during one request cycle unless you want to.

It is also possible to use the inclusion via the prefix typo3_encore in backend specific contexts. For example like so:

<f:be.container includeCssFiles="{0: 'typo3_encore:backend'}" includeJsFiles="{0: 'typo3_encore:backend'}">

</f:be.container>

HTTP/2 Preloading

All css and javascript files managed by the extension will be added to the AssetRegistry class during rendering. For these assets a Link HTTP header is created, which are the key to optimize the application performance when using HTTP/2 and preloading capabilities of modern web browsers.

Technically this is done by a PSR-15 Middleware.

If you want to add additional files to the AssetRegistry you can use the PreloadViewHelper:

<html
    xmlns:f="http://typo3.org/ns/TYPO3/CMS/Fluid/ViewHelpers"
    xmlns:encore="http://typo3.org/ns/Ssch/Typo3Encore/ViewHelpers"
    data-namespace-typo3-fluid="true"
>

<encore:preload attributes="{type: 'font/woff2', crossOrigin: 'anonymous'}" as="font" uri="{encore:asset(pathToFile: 'EXT:typo3_encore/Resources/fonts/webfont.woff2')}" />

</html>

Watch out, the example also uses the AssetViewHelper. The AssetViewHelper behind the scenes makes a look up to the manifest.json file. So you can also leverage the versioning feature provided by Webpack.

Static assets

Sometimes you might need to reference static assets (like image files) directly in your fluid templates. You can use the Encore copyFiles function to instruct Webpack to copy static assets to your output folder (see https://symfony.com/doc/current/frontend/encore/copy-files.html#referencing-image-files-from-a-template).

To reference a static asset file from a fluid template, you can then use the AssetViewHelper to get the file path (including the hash if versioning is enabled).

Note that the AssetViewHelper does not render anything but just returns the path to the file, so you will probably use inline notation to, e.g., display an image:

<html
    xmlns:f="http://typo3.org/ns/TYPO3/CMS/Fluid/ViewHelpers"
    xmlns:encore="http://typo3.org/ns/Ssch/Typo3Encore/ViewHelpers"
    data-namespace-typo3-fluid="true"
>

<img class="my-image" src="{encore:asset(pathToFile: 'EXT:my_extension/Resources/Public/Build/images/my_image.jpg')}" alt="My image" />

</html>

This way of using the AssetViewHelper is similar to the asset function used in Twig templates with Symfony.

Additional

If you are in production mode and set enableVersioning(true) then you should set the option
```
$GLOBALS['TYPO3_CONF_VARS']['FE']['versionNumberInFilename'] = ''
```

Defining Multiple Webpack Configurations (see)

Then you have to define your builds in your TypoScript-Setup:

 plugin.tx_typo3encore {
     settings {
         builds {
             firstBuild = EXT:typo3_encore/Resources/Public/FirstBuild
             secondBuild = EXT:typo3_encore/Resources/Public/SecondBuild
         }
     }
 }

Finally, you can specify which build to use:

 page.includeCSS {
     # Pattern PKG:typo3_encore:buildName:entryName
     app = PKG:typo3_encore:firstBuild:app
 }

<html
    xmlns:f="http://typo3.org/ns/TYPO3/CMS/Fluid/ViewHelpers"
    xmlns:encore="http://typo3.org/ns/Ssch/Typo3Encore/ViewHelpers"
    data-namespace-typo3-fluid="true"
>

<encore:renderWebpackLinkTags entryName="app" buildName="firstBuild"/>

</html>

Important note on TYPO3 JS/CSS concatenation and compression while working with encore dev-server mode

If you are using the Encore dev server (encore dev-server), ensure that TYPO3's asset concatenation and compression are disabled.

Enabling these options (config.concatenateCss = 1, config.concatenateJs = 1, config.compressCss = 1, or config.compressJs = 1) will prevent the dev server's hot module replacement (HMR) from working correctly. Additionally, TYPO3 may produce a large volume of temporary files (potentially gigabytes), significantly slowing down Docker-based development environments.

See Issue #234 for more details.

Example TypoScript to disable concatenation/compression in Development:
```
[like(applicationContext, "Development*")]
  config {
    compressCss = 0
    concatenateCss = 0
    compressJs = 0
    concatenateJs = 0
  }
[global]
```

CSS for CKEditor

It is possible to configure encore so that you can use a CSS file for the CKEditor which is generated by webpack and even works with enabled versioning. Two steps are required to do so:

Define an entrypoint for the RTE in your webpack.config.js, e.g.

Encore
    .addStyleEntry('rte', './assets/rte.scss')

Add in the CKEditor yaml configuration

editor:
  config:
    contentsCss: "typo3_encore:rte"

Add encore basic configuration to global TypoScript in ext_localconf.php

See https://docs.typo3.org/c/typo3/cms-core/main/en-us/Changelog/14.0/Breaking-105728-ExtbaseBackendModulesDoNotGuessPageIdForTypoScriptAnymore.html

ExtensionManagementUtility::addTypoScriptConstants(
    "@import 'EXT:typo3_encore/Configuration/TypoScript/constants.typoscript'
    @import 'EXT:site_package/Configuration/TypoScript/Constants/plugin.tx_typo3encore.typoscript'",
    false
);
ExtensionManagementUtility::addTypoScriptSetup(
    "@import 'EXT:typo3_encore/Configuration/TypoScript/setup.typoscript'",
    false
);

Getting Started with Webpack Encore

Although the documentation of Webpack Encore is awesome, i am going to provide a minimalistic how to install the frontend related things. I assume some basic knowledge of modern frontend development.

Install Encore into your project via Yarn or Npm:

First, make sure you install Node.js and also the Yarn or npm package manager.

yarn add @symfony/webpack-encore --dev

This command creates or modifies a package.json file and downloads dependencies into a node_modules/ directory. Yarn also creates/updates a yarn.lock (called package-lock.json if you use npm).

You should commit package.json and yarn.lock (or package-lock.json if using npm) to version control, but ignore the node_modules/ folder.

Creating the webpack.config.js File

Next, we are going to create a webpack.config.js file at the root of our project. This is the main config file for both Webpack and Webpack Encore:

var Encore = require('@symfony/webpack-encore');

Encore
    // the directory where compiled assets will be stored
    .setOutputPath('public/typo3conf/ext/my_sitepackage/Resources/Public/')

    // public path used by the web server to access the output path
    .setPublicPath('/typo3conf/ext/my_sitepackage/Resources/Public/')

    // only needed for CDN's or sub-directory deploy
    // .setManifestKeyPrefix('build/')

    // Copy some static images to your -> https://symfony.com/doc/current/frontend/encore/copy-files.html
    .copyFiles({
        from: './src/images',
        // Optional target path, relative to the output dir
        to: 'images/[path][name].[ext]',
        includeSubdirectories: false,
        // if versioning is enabled, add the file hash too
        to: 'images/[path][name].[hash:8].[ext]',
        // only copy files matching this pattern
        pattern: /\.(png|jpg|jpeg)$/
    })

    /*
     * ENTRY CONFIG
     *
     * Add 1 entry for each "page" of your app
     * (including one that's included on every page - e.g. "app")
     *
     * Each entry will result in one JavaScript file (e.g. app.js)
     * and one CSS file (e.g. app.css) if you JavaScript imports CSS.
     */
    .addEntry('app', './src/js/app.js')
    .addEntry('homepage', './src/js/homepage.js')

    // will require an extra script tag for runtime.js
    // but, you probably want this, unless you're building a single-page app
    .enableSingleRuntimeChunk()

    .cleanupOutputBeforeBuild()
    .enableSourceMaps(!Encore.isProduction())

    // enables hashed filenames (e.g. app.abc123.css)
    .enableVersioning(Encore.isProduction())

    // uncomment if you use TypeScript -> https://symfony.com/doc/current/frontend/encore/typescript.html
    // .enableTypeScriptLoader()

    // uncomment if you are using Sass/SCSS files -> https://symfony.com/doc/current/frontend/encore/css-preprocessors.html
    // .enableSassLoader()

    // uncomment if you're having problems with a jQuery plugin -> https://symfony.com/doc/current/frontend/encore/legacy-applications.html
    // .autoProvidejQuery()

    // uncomment if you use the postcss -> https://symfony.com/doc/current/frontend/encore/postcss.html
    // .enablePostCssLoader()


    // uncomment if you want to use vue -> https://symfony.com/doc/current/frontend/encore/vuejs.html
    // .enableVueLoader()

    // uncomment if you´re want to lint your sources
    // .enableEslintLoader()

    // uncomment if you´re want to have integrity hashes for your script tags, the extension takes care of it
    // .enableIntegrityHashes()

    // uncomment if you´re want to share general code for the different entries -> https://symfony.com/doc/current/frontend/encore/split-chunks.html
    // .splitEntryChunks()
    ;

// Uncomment if you are going to use a CDN -> https://symfony.com/doc/current/frontend/encore/cdn.html
// if (Encore.isProduction()) {
    //Encore.setPublicPath('https://my-cool-app.com.global.prod.fastly.net');

    // guarantee that the keys in manifest.json are *still*
    // prefixed with build/
    // (e.g. "build/dashboard.js": "https://my-cool-app.com.global.prod.fastly.net/dashboard.js")
    // Encore.setManifestKeyPrefix('build/');
// }

module.exports = Encore.getWebpackConfig();

Working with Watcher & TYPO3 with Content Security Policy

If you encounter problems with Content Security Policy and watcher add the following to your additional.php

// disable CSP if "npm run watch" is used
if (strpos(file_get_contents(\TYPO3\CMS\Core\Core\Environment::getPublicPath() . '/build/entrypoints.json'), 'build/vendors-node_modules') !== false) {
    $GLOBALS['TYPO3_CONF_VARS']['SYS']['features']['security.frontend.enforceContentSecurityPolicy'] = false;
}

Working with typo3/cms-composer-installers 4+ or TYPO3 12

The typo3/cms-composer-installers library takes care of moving TYPO3-specific assets in the right place in Composer-based installations, like copying extensions to typo3conf/ext. Starting with version 4.0 (currently at RC1 stage), the extensions will remain in vendor/vendor_name. The Resources/Public directory of each extension is symlinked from the public/assets directory using hashes. While it is possible to target the symlink, the fact that it is a hash makes it a bit flaky.

The recommendation is to use another build directory, not located inside an extension. As an example, asuming that you use public/build, the configuration in webpack.config.js would be modified as follows:

var Encore = require('@symfony/webpack-encore');

Encore
    .setOutputPath('../../public/_assets/build')
    .setPublicPath('/_assets/build')
    ...

The TypoScript constants have to be modified accordingly:

plugin.tx_typo3encore {
    settings {
        # These paths are relative to the web root (public) directory
        entrypointJsonPath = build/entrypoints.json
        manifestJsonPath = build/manifest.json
    }
}

If the site base configuration (config/sites/yoursite/config.yaml) is a subdirectory/subpath of your domain, it is required to add your new "build" directory as an additional absolute directory. This can be done in your "Configure Installation-Wide Options" (TYPO3 <= 11: typo3conf/LocalConfiguration.php; TYPO3 >= 12: config/system/settings.php)

    [FE][additionalAbsRefPrefixDirectories]: build

The realm of Webpack plugins

Encore already ships with a lot of useful plugins for the daily work. But someday you are gonna get to the point where you need more.

Generating icons and inject them automatically

Install webapp-webpack-plugin and html-webpack-plugin.

const WebappWebpackPlugin = require('webapp-webpack-plugin');
const HtmlWebpackPlugin = require('html-webpack-plugin');

Encore.addPlugin(new HtmlWebpackPlugin(
            {
                inject: false,
                minify: false,
                template: 'public/typo3conf/ext/typo3_encore/Resources/Private/Templates/Favicons.html',
                filename: 'favicons.html',
            }
        ))
        .addPlugin(new WebappWebpackPlugin({
            inject: htmlPlugin => htmlPlugin.options.filename === 'favicons.html',
            logo: './src/images/logo.png',
            force: true,
            favicons: {
                start_url: null,
                lang: null,
                icons: {
                    android: true,
                    appleIcon: true,
                    appleStartup: true,
                    windows: true,
                    yandex: true,
                    favicons: true,
                    coast: true,
                    firefox: true,
                    opengraph: false,
                    twitter: false
                }
            }
        }))

In order to inject the html file in the header of your TYPO3 just include the template file:

page.headerData.2039 = FLUIDTEMPLATE
page.headerData.2039 {
    file = EXT:typo3_encore/Resources/Public/favicons.html
}

Generating a svg sprite

Install svg-sprite-loader

const SpritePlugin = require('svg-sprite-loader/plugin');

Encore.addLoader({
    test: /\src\/icons\/.svg$/,
    loader: 'svg-sprite-loader',
    options: {
        extract: true,
    }
}).addPlugin(new SpritePlugin())

Now you have to import all your svg files in your javascript

function requireAll(r) {
    r.keys().forEach(r);
}
requireAll(require.context('./relative-path-to-svg-folder/svg-sprite/', true, /\.svg$/));

The extension ships with a SvgViewHelper in order to simplify the usage of svg in fluid.

<html
    xmlns:f="http://typo3.org/ns/TYPO3/CMS/Fluid/ViewHelpers"
    xmlns:encore="http://typo3.org/ns/Ssch/Typo3Encore/ViewHelpers"
    data-namespace-typo3-fluid="true"
>

<encore:svg title="Title" description="Description" src="EXT:typo3_encore/Resources/Public/sprite.svg" name="icon-fax-contact"/>

</html>

ssch/typo3-encore 适用场景与选型建议

ssch/typo3-encore 是一款基于 PHP 开发的 Composer 扩展包，目前已累计 494.92k 次下载、GitHub Stars 达 107，最近一次更新时间为 2019 年 04 月 10 日，在 PHP 生态内属于活跃度较高的组件。

它主要适用于以下技术方向：「webpack」「encore」等业务场景。在实际项目中，围绕这些方向常见需要落地的问题包括：接口对接、性能调优、并发安全、与既有框架（Laravel / ThinkPHP / Yii / Webman 等）的兼容适配，以及生产环境的日志埋点与稳定性保障。

我们在过去多个企业项目中使用过 ssch/typo3-encore 或与其功能相近的方案，如果你在选型或落地过程中遇到问题，例如 版本兼容、二次改造、私有化封装、与内部系统对接、生产 BUG 排查，欢迎联系我们协助评估。

围绕 ssch/typo3-encore 我们能提供哪些服务？

定制开发 / 二次开发

基于 ssch/typo3-encore 在你已有业务上做功能扩展、字段裁剪、UI 适配、与内部账号 / 权限 / 日志系统的深度对接。

BUG 修复 & 性能优化

线上偶发问题、内存泄漏、慢查询、并发异常等排查修复；针对高流量场景做缓存、队列、索引层面的调优。

项目外包 & 长期维护

承接完整的项目从需求 → 设计 → 开发 → 上线 → 长期运维；也可按月提供技术保姆服务。

yvsm@zunyunkeji.com QQ：316430983 微信：yvsm316 西安尊云信息科技 · 专注 PHP / Go / 分布式系统研发

与 ssch/typo3-encore 相关的其它包

同方向 / 同关键字的高下载量 PHP Composer 包推荐，方便对比选型：

bluetel-solutions/webpack-manifest-bundle 0

Webpack Manifest support

encoredigitalgroup/dynamicdata 2

Dynamic Data Fields for Laravel

malyusha/laravel-webpack-assets 6

Package to use WebpackManifestPlugin in laravel

ntpages/laravel-encore 0

Symfony's Webpack Encore for Laravel

debricked/datatablesbundle 1

Symfony Datatable Bundle For Doctrine2 Entities

contaoblackforest/contao-encore-bundle 5

Contao Encore Bundle

ssch/typo3-encore

包简介

关键字：