Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit 946d224

Browse filesBrowse files
weaverryanweaverryan
committed
Merge branch '3.4'
* 3.4: Fixes for #8084 thanks to Stof Tweaks thanks to Javier Use Twig's namespaced paths adding anotehr faq for old packages without a main script minor rewording [Encore] Adding more FAQs for #8072 [Encore] Documenting addPlugin - see #8070 Documenting (better) how to expose global variables - see #8071 [Encore] Adding docs about deploying to a subdirectory - see #8069 Adding docs about adding custom config - see #8067 Add missing link to handlebars-loader Add docs for custom loaders [#8004] some minor tweaks document new framework.assets.json_manifest_path option Minor reword Clearify setup of basic auth for test environment Update workflow.rst rearrange how workflow events are presented adding note about extracting CSS Adding note about browserslist config
2 parents 40aaf42 + c0a172a commit 946d224
Copy full SHA for 946d224

17 files changed

+474
-65
lines changed

‎assetic/asset_management.rst

Copy file name to clipboardExpand all lines: assetic/asset_management.rst
+5-4Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -552,10 +552,11 @@ done from the template and is relative to the public document root:
552552
553553
.. note::
554554

555-
Symfony also contains a method for cache *busting*, where the final URL
556-
generated by Assetic contains a query parameter that can be incremented
557-
via configuration on each deployment. For more information, see the
558-
:ref:`reference-framework-assets-version` configuration option.
555+
Symfony provides various cache busting implementations via the
556+
:ref:`version <reference-framework-assets-version>`,
557+
:ref:`version_format <reference-assets-version-format>`, and
558+
:ref:`json_manifest_path <reference-assets-json-manifest-path>`
559+
configuration options.
559560

560561
.. _assetic-dumping:
561562

‎components/workflow.rst

Copy file name to clipboardExpand all lines: components/workflow.rst
+2-2Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -44,8 +44,8 @@ these statuses are called **places**. You can define the workflow like this::
4444
use Symfony\Component\Workflow\Workflow;
4545
use Symfony\Component\Workflow\MarkingStore\SingleStateMarkingStore;
4646

47-
$definition = new DefinitionBuilder()
48-
->addPlaces(['draft', 'review', 'rejected', 'published'])
47+
$definition = new DefinitionBuilder();
48+
$definition->addPlaces(['draft', 'review', 'rejected', 'published'])
4949
// Transitions are defined with a unique name, an origin place and a destination place
5050
->addTransition(new Transition('to_review', 'draft', 'review'))
5151
->addTransition(new Transition('publish', 'review', 'published'))

‎frontend.rst

Copy file name to clipboardExpand all lines: frontend.rst
+9Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@ working with CSS and JavaScript a joy. You can use it, use something else, or ju
66
create static CSS and JS files in your ``web/`` directory and include them in your
77
templates.
88

9+
.. _frontend-webpack-encore:
10+
911
Webpack Encore
1012
--------------
1113

@@ -56,6 +58,13 @@ Guides
5658
* :doc:`jQuery and Legacy Applications </frontend/encore/legacy-apps>`
5759
* :doc:`Passing Information from Twig to JavaScript </frontend/encore/server-data>`
5860
* :doc:`webpack-dev-server and Hot Module Replacement (HMR) </frontend/encore/dev-server>`
61+
* :doc:`Adding custom loaders & plugins </frontend/encore/custom-loaders-plugins>`
62+
* :doc:`Advanced Webpack Configuration </frontend/encore/advanced-config>`
63+
64+
Troubleshooting
65+
...............
66+
67+
* :doc:`FAQ & Common Issues </frontend/encore/faq>`
5968

6069
Full API
6170
........

‎frontend/custom_version_strategy.rst

Copy file name to clipboardExpand all lines: frontend/custom_version_strategy.rst
+11-5Lines changed: 11 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -10,11 +10,17 @@ applications by adding a version identifier to the URL of the static assets
1010
identifier is also modified to force the browser to download it again instead of
1111
reusing the cached asset.
1212

13-
Symfony supports asset versioning thanks to the :ref:`version <reference-framework-assets-version>`
14-
and :ref:`version_format <reference-assets-version-format>` configuration
15-
options. If your application requires a more advanced versioning, such as
16-
generating the version dynamically based on some external information, you can
17-
create your own version strategy.
13+
If your application requires advanced versioning, such as generating the
14+
version dynamically based on some external information, you can create your
15+
own version strategy.
16+
17+
.. note::
18+
19+
Symfony provides various cache busting implementations via the
20+
:ref:`version <reference-framework-assets-version>`,
21+
:ref:`version_format <reference-assets-version-format>`, and
22+
:ref:`json_manifest_path <reference-assets-json-manifest-path>`
23+
configuration options.
1824

1925
Creating your Own Asset Version Strategy
2026
----------------------------------------

‎frontend/encore/advanced-config.rst

Copy file name to clipboard
+44Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
Advanced Webpack Config
2+
=======================
3+
4+
Quite simply, Encore generates the Webpack configuration that's used in your
5+
``webpack.config.js`` file. Encore doesn't support adding all of Webpack's
6+
`configuration options`_, because many can be easily added on your own.
7+
8+
For example, suppose you need to set `Webpack's watchOptions`_ setting. To do that,
9+
modify the config after fetching the it from Encore:
10+
11+
.. code-block:: javascript
12+
13+
// webpack.config.js
14+
15+
var Encore = require('@symfony/webpack-encore');
16+
17+
// ... all Encore config here
18+
19+
// fetch the config, then modify it!
20+
var config = Encore.getWebpackConfig();
21+
config.watchOptions = { poll: true, ignored: /node_modules/ };
22+
23+
// other examples: add an alias or extension
24+
// config.resolve.alias.local = path.resolve(__dirname, './resources/src');
25+
// config.resolve.extensions.push('json');
26+
27+
// export the final config
28+
module.exports = config;
29+
30+
But be careful not to accidentally override any config from Encore:
31+
32+
.. code-block:: javascript
33+
34+
// webpack.config.js
35+
// ...
36+
37+
// GOOD - this modifies the config.resolve.extensions array
38+
config.resolve.extensions.push('json');
39+
40+
// BAD - this replaces any extensions added by Encore
41+
// config.resolve.extensions = ['json'];
42+
43+
.. _`configuration options`: https://webpack.js.org/configuration/
44+
.. _`Webpack's watchOptions`: https://webpack.js.org/configuration/watch/#watchoptions

‎frontend/encore/custom-loaders-plugins.rst

Copy file name to clipboard
+64Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
Adding Custom Loaders & Plugins
2+
===============================
3+
4+
Adding Custom Loaders
5+
---------------------
6+
7+
Encore already comes with a variety of different loaders out of the box,
8+
but if there is a specific loader that you want to use that is not currently supported, you
9+
can add your own loader through the ``addLoader`` function.
10+
The ``addLoader`` takes any valid webpack rules config.
11+
12+
If, for example, you want to add the `handlebars-loader`_, call ``addLoader`` with
13+
your loader config
14+
15+
.. code-block:: javascript
16+
17+
Encore
18+
// ...
19+
.addLoader({ test: /\.handlebars$/, loader: 'handlebars-loader' })
20+
;
21+
22+
Since the loader config accepts any valid Webpack rules object, you can pass any
23+
additional information your need for the loader
24+
25+
.. code-block:: javascript
26+
27+
Encore
28+
// ...
29+
.addLoader({
30+
test: /\.handlebars$/,
31+
loader: 'handlebars-loader',
32+
options: {
33+
helperDirs: [
34+
__dirname + '/helpers1',
35+
__dirname + '/helpers2',
36+
],
37+
partialDirs: [
38+
path.join(__dirname, 'templates', 'partials')
39+
]
40+
}
41+
})
42+
;
43+
44+
Adding Custom Plugins
45+
---------------------
46+
47+
Encore uses a variety of different `plugins`_ internally. But, you can add your own
48+
via the ``addPlugin()`` method. For example, if you use `Moment.js`_, you might want
49+
to use the `IgnorePlugin`_ (see `moment/moment#2373`_):
50+
51+
.. code-block:: diff
52+
53+
// webpack.config.js
54+
Encore
55+
// ...
56+
57+
+ .addPlugin(new webpack.IgnorePlugin(/^\.\/locale$/, /moment$/))
58+
;
59+
60+
.. _`handlebars-loader`: https://github.com/pcardune/handlebars-loader
61+
.. _`plugins`: https://webpack.js.org/plugins/
62+
.. _`Moment.js`: https://momentjs.com/
63+
.. _`IgnorePlugin`: https://webpack.js.org/plugins/ignore-plugin/
64+
.. _`moment/moment#2373`: https://github.com/moment/moment/issues/2373

‎frontend/encore/faq.rst

Copy file name to clipboard
+80Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
FAQ and Common Issues
2+
=====================
3+
4+
My App Lives under a Subdirectory
5+
---------------------------------
6+
7+
If your app does not live at the root of your web server (i.e. it lives under a subdirectory,
8+
like ``/myAppSubdir``), you just need to configure that when calling ``Encore.setPublicPrefix()``:
9+
10+
.. code-block:: diff
11+
12+
// webpack.config.js
13+
Encore
14+
// ...
15+
16+
.setOutputPath('web/build/')
17+
18+
- .setPublicPath('/build')
19+
+ // this is your *true* public path
20+
+ .setPublicPath('/myAppSubdir/build')
21+
22+
+ // this is now needed so that your manifest.json keys are still `build/foo.js`
23+
+ // i.e. you won't need to change anything in your Symfony app
24+
+ .setManifestKeyPrefix('build')
25+
;
26+
27+
If you're :ref:`processing your assets through manifest.json <load-manifest-files>`,
28+
you're done! The ``manifest.json`` file will now include the subdirectory in the
29+
final paths:
30+
31+
.. code-block:: json
32+
33+
{
34+
"build/app.js": "/myAppSubdir/build/app.123abc.js",
35+
"build/dashboard.css": "/myAppSubdir/build/dashboard.a4bf2d.css"
36+
}
37+
38+
"jQuery is not defined" or "$ is not defined"
39+
---------------------------------------------
40+
41+
This error happens when your code (or some library that you are using) expects ``$``
42+
or ``jQuery`` to be a global variable. But, when you use Webpack and ``require('jquery')``,
43+
no global variables are set.
44+
45+
The fix depends on if the error is happening in your code or inside some third-party
46+
code that you're using. See :doc:`/frontend/encore/legacy-apps` for the fix.
47+
48+
Uncaught ReferenceError: webpackJsonp is not defined
49+
----------------------------------------------------
50+
51+
If you get this error, it's probably because you've just added a :doc:`shared entry </frontend/encore/shared-entry>`
52+
but you *forgot* to add a ``script`` tag for the new ``manifest.js`` file. See the
53+
information about the :ref:`script tags <encore-shared-entry-script>` in that section.
54+
55+
This dependency was not found: some-module in ./path/to/file.js
56+
---------------------------------------------------------------
57+
58+
Usually, after you install a package via yarn, you can require / import it to use
59+
it. For example, after running ``yarn add respond.js``, you try to require that module:
60+
61+
.. code-block:: javascript
62+
63+
require('respond.js');
64+
65+
But, instead of working, you see an error:
66+
67+
This dependency was not found:
68+
69+
* respond.js in ./app/Resources/assets/js/app.js
70+
71+
Typically, a package will "advertise" its "main" file by adding a ``main`` key to
72+
its ``package.json``. But sometimes, old libraries won't have this. Instead, you'll
73+
need to specifically require the file you need. In this case, the file you should
74+
use is located at ``node_modules/respond.js/dest/respond.src.js``. You can require
75+
this via:
76+
77+
.. code-block:: javascript
78+
79+
// require a non-minified file whenever possible
80+
require('respond.js/dest/respond.src.js');

‎frontend/encore/legacy-apps.rst

Copy file name to clipboardExpand all lines: frontend/encore/legacy-apps.rst
+38-6Lines changed: 38 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,21 @@
11
jQuery and Legacy Applications
22
==============================
33

4+
Inside Webpack, when you require a module, it does *not* (usually) set a global variable.
5+
Instead, it just returns a value:
6+
7+
.. code-block:: javascript
8+
9+
// this loads jquery, but does *not* set a global $ or jQuery variable
10+
const $ = require('jquery');
11+
12+
In practice, this will cause problems with some outside libraries that *rely* on
13+
jQuery to be global. It will be a problem if some of *your* JavaScript isn't being
14+
processed through Webpack (e.g. you have some JavaScript in your templates).
15+
16+
Using Libraries that Expect jQuery to be Global
17+
-----------------------------------------------
18+
419
Some legacy JavaScript applications use programming practices that don't play
520
well with the new practices promoted by Webpack. The most common of these
621
problems is using code (e.g. jQuery plugins) that assume that jQuery is already
@@ -27,7 +42,7 @@ So, when working with legacy applications, you may need to add the following to
2742
+ .autoProvidejQuery()
2843
;
2944
30-
Internally, this ``autoProvidejQuery()`` method uses the ``autoProvideVariables()``
45+
Internally, this ``autoProvidejQuery()`` method calls the ``autoProvideVariables()``
3146
method from Encore. In practice, it's equivalent to doing:
3247

3348
.. code-block:: javascript
@@ -38,16 +53,33 @@ method from Encore. In practice, it's equivalent to doing:
3853
.autoProvideVariables({
3954
$: 'jquery',
4055
jQuery: 'jquery'
56+
'window.jQuery': 'jquery',
4157
})
4258
// ...
4359
;
4460
61+
Accessing jQuery from outside of Webpack JavaScript Files
62+
---------------------------------------------------------
63+
4564
If you also need to provide access to ``$`` and ``jQuery`` variables outside of
46-
JavaScript files processed by Webpack, you must create the global variables
47-
yourself in some file loaded before the legacy JavaScript code. For example, you
48-
can define a ``common.js`` file processed by Webpack and loaded in every page
49-
with the following content:
65+
JavaScript files processed by Webpack (e.g. JavaScript that still lives in your
66+
templates), you need to manually set these as global variables in some JavaScript
67+
file that is loaded before your legacy code.
68+
69+
For example, you could define a ``common.js`` file that's processed by Webpack and
70+
loaded on every page with the following content:
5071

5172
.. code-block:: javascript
5273
53-
window.$ = window.jQuery = require('jquery');
74+
// require jQuery normally
75+
const $ = require('jquery');
76+
77+
// create global $ and jQuery variables
78+
global.$ = global.jQuery = $;
79+
80+
.. tip::
81+
82+
The ``global`` variable is a special way of setting things in the ``window``
83+
variable. In a web context, using ``global`` and ``window`` are equivalent,
84+
except that ``window.jQuery`` won't work when using ``autoProvidejQuery()``.
85+
In other words, use ``global``.

‎frontend/encore/postcss.rst

Copy file name to clipboardExpand all lines: frontend/encore/postcss.rst
+25Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,8 @@ Next, create a ``postcss.config.js`` file at the root of your project:
1818
plugins: {
1919
// include whatever plugins you want
2020
// but make sure you install these via yarn or npm!
21+
22+
// add browserslist config to package.json (see below)
2123
autoprefixer: {}
2224
}
2325
}
@@ -35,6 +37,29 @@ Then, Enable the loader in Encore!
3537
3638
That's it! The ``postcss-loader`` will now be used for all CSS, Sass, etc files.
3739

40+
Adding browserslist to package.json
41+
-----------------------------------
42+
43+
The ``autoprefixer`` (and many other tools) need to know what browsers you want to
44+
support. The best-practice is to configure this directly in your ``package.json``
45+
(so that all the tools can read this):
46+
47+
.. code-block:: diff
48+
49+
{
50+
+ "browserslist": [ "last 2 versions", "ios >= 8" ]
51+
}
52+
53+
See `browserslist`_ for more details on the syntax.
54+
55+
.. note::
56+
57+
Encore uses `babel-preset-env`_, which *also* needs to know which browsers you
58+
want to support. But this does *not* read the ``browserslist`` config key. You
59+
must configure the browsers separately via :doc:`configureBabel() </frontend/encore/babel>`.
60+
3861
.. _`PostCSS`: http://postcss.org/
3962
.. _`autoprefixing`: https://github.com/postcss/autoprefixer
4063
.. _`linting`: https://stylelint.io/
64+
.. _`browserslist`: https://github.com/ai/browserslist
65+
.. _`babel-preset-env`: https://github.com/babel/babel-preset-env

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.