Skip to content

Reworded some explanations in the basic Webpack Encore example #8204

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Nov 16, 2017
Merged

Reworded some explanations in the basic Webpack Encore example #8204

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
381570d
Reworded some explanations in the basic Webpack Encore example
javiereguiluz Jul 21, 2017
f855793
Typo
javiereguiluz Jul 21, 2017
478b93d
More rewords and removed the addStyleEntry() method
javiereguiluz Aug 7, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 32 additions & 34 deletions frontend/encore/simple-example.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,20 @@ First Example
Imagine you have a simple project with one CSS and one JS file, organized into
an ``assets/`` directory:

* ``assets/js/main.js``
* ``assets/css/global.scss``
* ``assets/js/app.js``
* ``assets/css/app.scss``

With Encore, we can easily minify these files, pre-process ``global.scss``
Let's consider that the project follows the recommended practice of importing
the CSS files for their associated JavaScript files:

.. code-block:: javascript

// assets/js/app.js
require('../css/app.scss');

// ...rest of JavaScript code here

With Encore, we can easily minify these files, pre-process ``app.scss``
through Sass and a *lot* more.

Configuring Encore/Webpack
Expand All @@ -22,20 +32,17 @@ Inside, use Encore to help generate your Webpack configuration.
var Encore = require('@symfony/webpack-encore');

Encore
// directory where all compiled assets will be stored
// the project directory where all compiled assets will be stored
.setOutputPath('web/build/')

// what's the public path to this directory (relative to your project's document root dir)
// the public path used by the web server to access the previous directory
.setPublicPath('/build')

// empty the outputPath dir before each build
.cleanupOutputBeforeBuild()

// will output as web/build/app.js
.addEntry('app', './assets/js/main.js')

// will output as web/build/global.css
.addStyleEntry('global', './assets/css/global.scss')
// will create web/build/app.js and web/build/app.css
.addEntry('app', './assets/js/app.js')

// allow sass/scss files to be processed
.enableSassLoader()
Expand Down Expand Up @@ -78,7 +85,7 @@ Actually, to use ``enableSassLoader()``, you'll need to install a few
more packages. But Encore will tell you *exactly* what you need.

After running one of these commands, you can now add ``script`` and ``link`` tags
to the new, compiled assets (e.g. ``/build/global.css`` and ``/build/app.js``).
to the new, compiled assets (e.g. ``/build/app.css`` and ``/build/app.js``).
In Symfony, use the ``asset()`` helper:

.. code-block:: twig
Expand All @@ -88,7 +95,7 @@ In Symfony, use the ``asset()`` helper:
<html>
<head>
<!-- ... -->
<link rel="stylesheet" href="{{ asset('build/global.css') }}">
<link rel="stylesheet" href="{{ asset('build/app.css') }}">
</head>
<body>
<!-- ... -->
Expand Down Expand Up @@ -119,7 +126,7 @@ Great! Use ``require()`` to import ``jquery`` and ``greet.js``:

.. code-block:: javascript

// assets/js/main.js
// assets/js/app.js

// loads the jquery package from node_modules
var $ = require('jquery');
Expand All @@ -136,32 +143,23 @@ That's it! When you build your assets, jQuery and ``greet.js`` will automaticall
be added to the output file (``app.js``). For common libraries like jQuery, you
may want also to :doc:`create a shared entry </frontend/encore/shared-entry>` for better performance.

Requiring CSS Files from JavaScript
-----------------------------------
Multiple JavaScript Entries
---------------------------

Above, you created an entry called ``app`` that pointed to ``main.js``:
The previous example is the best way to deal with SPA (Single Page Applications)
and very simple applications. However, as your application grows, you'll need to
define more entries with the JavaScript and CSS code of some specific sections
(homepage, blog, store, etc.)

.. code-block:: javascript

Encore
// ...
.addEntry('app', './assets/js/main.js')
.addEntry('homepage', './assets/js/homepage.js')
.addEntry('blog', './assets/js/blog.js')
.addEntry('store', './assets/js/store.js')
;

Once inside ``main.js``, you can even require CSS files:

.. code-block:: javascript

// assets/js/main.js
// ...

// a CSS file with the same name as the entry js will be output
require('../css/main.scss');

Now, both an ``app.js`` **and** an ``app.css`` file will be created. You'll need
to add a link tag to the ``app.css`` file in your templates:

.. code-block:: diff

<link rel="stylesheet" href="{{ asset('build/global.css') }}">
+ <link rel="stylesheet" href="{{ asset('build/app.css') }}">
If those entries include CSS/Sass files (e.g. ``homepage.js`` requires
``assets/css/homepage.scss``), two files will be generated for each of them
(e.g. ``build/homepage.js`` and ``build/homepage.css``).