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 ae308d9

Browse filesBrowse files
weaverryanweaverryan
committed
feature symfony#8026 Encore docs (weaverryan)
This PR was squashed before being merged into the 3.3 branch (closes symfony#8026). Discussion ---------- Encore docs Initial work on the Encore docs. 🎆 This PR was approved by the team on a different PR. Tweaks and fixes in via PR's are warmly welcomed! Commits ------- cf411b8 Encore docs
2 parents f59a815 + cf411b8 commit ae308d9
Copy full SHA for ae308d9
Expand file treeCollapse file tree

16 files changed

+876
-2
lines changed

‎frontend.rst

Copy file name to clipboard
+77-2Lines changed: 77 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,83 @@
1-
Front-end
2-
=========
1+
Managing CSS and JavaScript
2+
===========================
3+
4+
Symfony ships with a pure-JavaScript library - called Webpack Encore - that makes
5+
working with CSS and JavaScript a joy. You can use it, use something else, or just
6+
create static CSS and JS files in your ``web/`` directory and include them in your
7+
templates.
8+
9+
Webpack Encore
10+
--------------
11+
12+
`Webpack Encore`_ is a simpler way to integrate `Webpack`_ into your application.
13+
It *wraps* Webpack, giving you a clean & powerful API for bundling JavaScript modules,
14+
pre-processing CSS & JS and compiling and minifying assets. Encore gives you professional
15+
asset system that's a *delight* to use.
16+
17+
Encore is inspired by `Webpacker`_ and `Mix`_, but stays in the spirit of Webpack:
18+
using its features, concepts and naming conventions for a familiar feel. It aims
19+
to solve the most common Webpack use cases.
20+
21+
.. tip::
22+
23+
Encore is made by `Symfony`_ and works *beautifully* in Symfony applications.
24+
But it can easily be used in any application... in any language!
25+
26+
Encore Documentation
27+
--------------------
28+
29+
Getting Started
30+
...............
31+
32+
* :doc:`Installation </frontend/encore/installation>`
33+
* :doc:`First Example </frontend/encore/simple-example>`
34+
35+
Adding more Features
36+
....................
37+
38+
* :doc:`CSS Preprocessors: Sass, LESS, etc </frontend/encore/css-preprocessors>`
39+
* :doc:`PostCSS and autoprefixing </frontend/encore/postcss>`
40+
* :doc:`Enabling React.js </frontend/encore/reactjs>`
41+
* :doc:`Configuring Babel </frontend/encore/babel>`
42+
* :doc:`Source maps </frontend/encore/sourcemaps>`
43+
44+
Optimizing
45+
..........
46+
47+
* :doc:`Versioning (and the manifest.json file) </frontend/encore/versioning>`
48+
* :doc:`Using A CDN </frontend/encore/cdn>`
49+
* :doc:`Creating a "Shared" entry for re-used modules </frontend/encore/shared-entry>`
50+
51+
Guides
52+
......
53+
54+
* :doc:`Using Bootstrap CSS & JS </frontend/encore/bootstrap>`
55+
* :doc:`Creating Page-Specific CSS/JS </frontend/encore/page-specific-assets>`
56+
* :doc:`jQuery and Legacy Applications </frontend/encore/legacy-apps>`
57+
* :doc:`Passing Information from Twig to JavaScript </frontend/encore/server-data>`
58+
* :doc:`webpack-dev-server and Hot Module Replacement (HMR) </frontend/encore/dev-server>`
59+
60+
Full API
61+
........
62+
63+
* `Full API`_: https://github.com/symfony/webpack-encore/blob/master/index.js
64+
65+
.. _`Webpack Encore`: https://www.npmjs.com/package/@symfony/webpack-encore
66+
.. _`Webpack`: https://webpack.js.org/
67+
.. _`Webpacker`: https://github.com/rails/webpacker
68+
.. _`Mix`: https://laravel.com/docs/5.4/mix
69+
.. _`Symfony`: http://symfony.com/
70+
.. _`Full API`: https://github.com/symfony/webpack-encore/blob/master/index.js
71+
372

473
.. toctree::
574
:maxdepth: 1
675
:glob:
776

877
frontend/*
78+
79+
.. toctree::
80+
:hidden:
81+
:glob:
82+
83+
frontend/encore/*

‎frontend/encore/babel.rst

Copy file name to clipboard
+30Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
Configuring Babel
2+
=================
3+
4+
`Babel`_ is automatically configured for all ``.js`` and ``.jsx`` files via the
5+
``babel-loader`` with sensible defaults (e.g. with the ``env`` preset and
6+
``react`` if requested).
7+
8+
Need to extend the Babel configuration further? The easiest way is via
9+
``configureBabel()``:
10+
11+
.. code-block:: javascript
12+
13+
// webpack.config.js
14+
// ...
15+
16+
Encore
17+
// ...
18+
19+
// modify the default Babel configuration
20+
.configureBabel(function(babelConfig) {
21+
babelConfig.presets.push('es2017');
22+
})
23+
;
24+
25+
You can also create a standard ``.babelrc`` file at the root of your project.
26+
Just make sure to configure it with all the presets you need: as soon as a
27+
``.babelrc`` is present, Encore can no longer add *any* Babel configuration for
28+
you!
29+
30+
.. _`Babel`: http://babeljs.io/

‎frontend/encore/bootstrap.rst

Copy file name to clipboard
+116Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
Using Bootstrap CSS & JS
2+
========================
3+
4+
Want to use Bootstrap (or something similar) in your project? No problem!
5+
First, install it. To be able to customize things further, we'll install
6+
``bootstrap-sass``:
7+
8+
.. code-block:: terminal
9+
10+
$ yarn add bootstrap-sass --dev
11+
12+
Importing Bootstrap Sass
13+
------------------------
14+
15+
Now that ``bootstrap-sass`` lives in your ``node_modules`` directory, you can
16+
import it from any Sass or JavaScript file. For example, if you're already have
17+
a ``global.scss`` file, import it from there:
18+
19+
.. code-block:: css
20+
21+
// assets/css/global.scss
22+
23+
// customize some Bootstrap variables
24+
$brand-primary: darken(#428bca, 20%);
25+
26+
// the ~ allows you to reference things in node_modules
27+
@import '~bootstrap-sass/assets/stylesheets/bootstrap';
28+
29+
That's it! This imports the ``node_modules/bootstrap-sass/assets/stylesheets/_bootstrap.scss``
30+
file into ``global.scss``. You can even customize the Bootstrap variables first!
31+
32+
.. tip::
33+
34+
If you don't need *all* of Bootstrap's features, you can include specific files
35+
in the ``bootstrap`` directory instead - e.g. ``~bootstrap-sass/assets/stylesheets/bootstrap/alerts``.
36+
37+
After including ``bootstrap-sass``, your Webpack builds might become slow. To fix
38+
this, you can use the ``resolve_url_loader`` option:
39+
40+
.. code-block:: diff
41+
42+
// webpack.config.js
43+
Encore
44+
+ enableSassLoader({
45+
+ 'resolve_url_loader' => false
46+
+ })
47+
;
48+
49+
This disables the ``resolve-url-loader`` in Webpack, which means that any
50+
``url()`` paths in your Sass files must now be relative to the original source
51+
entry file instead of whatever file you're inside of (see `Problems with url()`_).
52+
To load Bootstrap, you'll need to override the path to its icons:
53+
54+
.. code-block:: diff
55+
56+
// assets/css/global.scss
57+
58+
+ $icon-font-path: "~bootstrap-sass/assets/fonts/bootstrap/";
59+
60+
+ // set if you're also including font-awesome
61+
+ // $fa-font-path: "~font-awesome/fonts";
62+
63+
@import '~bootstrap-sass/assets/stylesheets/bootstrap';
64+
65+
Importing Bootstrap JavaScript
66+
------------------------------
67+
68+
Bootstrap JavaScript requires jQuery, so make sure you have this installed:
69+
70+
.. code-block:: terminal
71+
72+
$ yarn add jquery --dev
73+
74+
Next, make sure call ``.autoProvidejQuery()`` in your ``webpack.config.js`` file:
75+
76+
.. code-block:: diff
77+
78+
// webpack.config.js
79+
Encore
80+
// ...
81+
+ .autoProvidejQuery()
82+
83+
This is needed because Bootstrap expects jQuery to be available as a global
84+
variable. Now, require bootstrap from any of your JavaScript files:
85+
86+
.. code-block:: javascript
87+
88+
// main.js
89+
90+
var $ = require('jquery');
91+
// JS is equivalent to the normal "bootstrap" package
92+
// no need to set this to a variable, just require it
93+
require('bootstrap-sass');
94+
95+
// or you can include specific pieces
96+
// require('bootstrap-sass/javascripts/bootstrap/tooltip');
97+
// require('bootstrap-sass/javascripts/bootstrap/popover');
98+
99+
$(document).ready(function() {
100+
$('[data-toggle="popover"]').popover();
101+
});
102+
103+
Thanks to ``autoProvidejQuery()``, you can require any other jQuery
104+
plugins in a similar way:
105+
106+
.. code-block:: javascript
107+
108+
// ...
109+
110+
// require the JavaScript
111+
require('bootstrap-star-rating');
112+
// require 2 CSS files needed
113+
require('bootstrap-star-rating/css/star-rating.css');
114+
require('bootstrap-star-rating/themes/krajee-svg/theme.css');
115+
116+
.. _`Problems with url()`: https://github.com/webpack-contrib/sass-loader#problems-with-url

‎frontend/encore/cdn.rst

Copy file name to clipboard
+47Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
Using a CDN
2+
===========
3+
4+
Are you deploying to a CDN? That's awesome :) - and configuring Encore for that is
5+
easy. Once you've made sure that your built files are uploaded to the CDN, configure
6+
it in Encore:
7+
8+
.. code-block:: diff
9+
10+
// webpack.config.js
11+
// ...
12+
13+
Encore
14+
.setOutputPath('web/build/')
15+
// in dev mode, don't use the CDN
16+
.setPublicPath('/build');
17+
// ...
18+
;
19+
20+
+ if (Encore.isProduction()) {
21+
+ Encore.setPublicPath('https://my-cool-app.com.global.prod.fastly.net');
22+
+
23+
+ // guarantee that the keys in manifest.json are *still*
24+
+ // prefixed with build/
25+
+ // (e.g. "build/dashboard.js": "https://my-cool-app.com.global.prod.fastly.net/dashboard.js")
26+
+ Encore.setManifestKeyPrefix('build/');
27+
+ }
28+
29+
That's it! Internally, Webpack will now know to load assets from your CDN -
30+
e.g. ``https://my-cool-app.com.global.prod.fastly.net/dashboard.js``.
31+
32+
.. note::
33+
34+
It's still your responsibility to put your assets on the CDN - e.g. by
35+
uploading them or by using "origin pull", where your CDN pulls assets
36+
directly from your web server.
37+
38+
You *do* need to make sure that the ``script`` and ``link`` tags you include on your
39+
pages also uses the CDN. Fortunately, the ``manifest.json`` paths are updated to
40+
point to the CDN. In Symfony, as long as you've configured
41+
:doc:`Asset Versioning </frontend/encore/versioning>`, you're done! The ``manifest.json``
42+
file includes the full CDN URL:
43+
44+
.. code-block:: twig
45+
46+
{# Your script/link tags don't need to change at all to support the CDN #}
47+
<script src="{{ asset('build/dashboard.js') }}"></script>

‎frontend/encore/css-preprocessors.rst

Copy file name to clipboard
+48Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
CSS Preprocessors: Sass, LESS, etc
2+
==================================
3+
4+
Using Sass
5+
----------
6+
7+
To use the Sass pre-processor, install the dependencies:
8+
9+
.. code-block:: terminal
10+
11+
$ yarn add --dev sass-loader node-sass
12+
13+
And enable it in ``webpack.config.js``:
14+
15+
.. code-block:: javascript
16+
17+
// webpack.config.js
18+
// ...
19+
20+
Encore
21+
// ...
22+
.enableSassLoader()
23+
;
24+
25+
That's it! All files ending in ``.sass`` or ``.scss`` will be processed.
26+
27+
Using LESS
28+
----------
29+
30+
To use the LESS pre-processor, install the dependencies:
31+
32+
.. code-block:: terminal
33+
34+
$ yarn add --dev less-loader less
35+
36+
And enable it in ``webpack.config.js``:
37+
38+
.. code-block:: javascript
39+
40+
// webpack.config.js
41+
// ...
42+
43+
Encore
44+
// ...
45+
.enableLessLoader()
46+
;
47+
48+
That's it! All files ending in ``.less`` will be pre-processed.

‎frontend/encore/dev-server.rst

Copy file name to clipboard
+31Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
Using webpack-dev-server and HMR
2+
================================
3+
4+
While developing, instead of using ``encore dev --watch``, you can instead use the
5+
`webpack-dev-server`_:
6+
7+
.. code-block:: terminal
8+
9+
$ ./node_modules/.bin/encore dev-server
10+
11+
This serves the built assets from a new server at ``http://localhost:8080`` (it does
12+
not actually write any files to disk). This means your ``script`` and ``link`` tags
13+
need to change to point to this.
14+
15+
If you've activated the :ref:`manifest.json versioning <load-manifest-files>`
16+
you're done: the paths in your templates will automatically point to the dev server.
17+
18+
You can also pass options to the ``dev-server`` command: any options that are supported
19+
by the normal `webpack-dev-server`_. For example:
20+
21+
.. code-block:: terminal
22+
23+
$ ./node_modules/.bin/encore dev-server --https --port 9000
24+
25+
This will start a server at ``https://localhost:9000``.
26+
27+
.. note::
28+
29+
Hot module replacement is not currently supported.
30+
31+
.. _`webpack-dev-server`: https://webpack.js.org/configuration/dev-server/

‎frontend/encore/installation.rst

Copy file name to clipboard
+31Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
Installation
2+
============
3+
4+
First, make sure you `install Node.js`_ and also the `yarn package manager`_.
5+
6+
Then, install Encore into your project with yarn:
7+
8+
.. code-block:: terminal
9+
10+
$ yarn add @symfony/webpack-encore --dev
11+
12+
.. note::
13+
14+
If you want to use `npm`_ instead of `yarn`_, replace ``yarn add xxx --dev`` by
15+
``npm install xxx --save-dev``.
16+
17+
This command creates (or modifies) a ``package.json`` file and downloads dependencies
18+
into a ``node_modules/`` directory. When using Yarn, a file called ``yarn.lock``
19+
is also created/updated. When using npm 5, a ``package-lock.json`` file is created/updated.
20+
21+
.. tip::
22+
23+
You should commit ``package.json`` and ``yarn.lock`` (or ``package-lock.json``
24+
if using npm) to version control, but ignore ``node_modules/``.
25+
26+
Next, create your ``webpack.config.js`` in :doc:`/frontend/encore/simple-example`!
27+
28+
.. _`install Node.js`: https://nodejs.org/en/download/
29+
.. _`yarn package manager`: https://yarnpkg.com/lang/en/docs/install/
30+
.. _`npm`: https://www.npmjs.com/
31+
.. _`yarn`: https://yarnpkg.com/

0 commit comments

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