Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit ae308d9

Browse 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

16 files changed

+876
-2
lines changed

‎frontend.rst

Lines 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

Lines 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

Lines 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

Lines 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

Lines 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

Lines 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

Lines 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)