First Example

Edit this page

Warning: You are browsing the documentation for Symfony 4.0, which is no longer maintained.

Read the updated version of this page for Symfony 7.0 (the current stable version).

First Example

Imagine you have a simple project with one CSS and one JS file, organized into an assets/ directory:

  • assets/js/app.js
  • assets/css/app.css

With Encore, you should think of CSS as a dependency of your JavaScript. This means, you will require whatever CSS you need from inside JavaScript:

1
2
3
4
// assets/js/app.js
require('../css/app.css');

// ...rest of JavaScript code here

With Encore, we can easily minify these files, pre-process app.css through PostCSS and a lot more.

Configuring Encore/Webpack

Create a new file called webpack.config.js at the root of your project. Inside, use Encore to help generate your Webpack configuration.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
// webpack.config.js
var Encore = require('@symfony/webpack-encore');

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

    // the public path used by the web server to access the previous directory
    .setPublicPath('/build')

    // will create public/build/app.js and public/build/app.css
    .addEntry('app', './assets/js/app.js')

    // allow legacy applications to use $/jQuery as a global variable
    .autoProvidejQuery()

    // enable source maps during development
    .enableSourceMaps(!Encore.isProduction())

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

    // show OS notifications when builds finish/fail
    .enableBuildNotifications()

    // create hashed filenames (e.g. app.abc123.css)
    // .enableVersioning()

    // allow sass/scss files to be processed
    // .enableSassLoader()
;

// export the final configuration
module.exports = Encore.getWebpackConfig();

This is already a rich setup: it outputs 2 files and enables source maps to help debugging.

To build the assets, use the encore executable:

1
2
3
4
5
6
7
8
9
10
11
12
13
# compile assets once
$ ./node_modules/.bin/encore dev

# recompile assets automatically when files change
$ ./node_modules/.bin/encore dev --watch

# compile assets, but also minify & optimize them
$ ./node_modules/.bin/encore production

# shorter version of the above 3 commands
$ yarn run encore dev
$ yarn run encore dev --watch
$ yarn run encore production

Note

Re-run encore each time you update your webpack.config.js file.

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

1
2
3
4
5
6
7
8
9
10
11
12
{# base.html.twig #}
<!DOCTYPE html>
<html>
    <head>
        <!-- ... -->
        <link rel="stylesheet" href="{{ asset('build/app.css') }}">
    </head>
    <body>
        <!-- ... -->
        <script src="{{ asset('build/app.js') }}"></script>
    </body>
</html>

Using Sass

Instead of using plain CSS you can also use Sass. In order to do so, change the extension of the app.css file to .sass or .scss (based on the syntax you want to use):

1
2
3
// assets/js/app.js
- require('../css/app.css');
+ require('../css/app.scss');

And enable the Sass pre-processor:

1
2
3
4
5
6
7
// webpack.config.js
Encore
    // ...

    // allow sass/scss files to be processed
-    // .enableSassLoader()
+    .enableSassLoader()

Using enableSassLoader() requires to install additional packages, but Encore will tell you exactly which ones when running it.

Requiring JavaScript Modules

Webpack is a module bundler... which means that you can require other JavaScript files. First, create a file that exports a function:

1
2
3
4
// assets/js/greet.js
module.exports = function(name) {
    return `Yo yo ${name} - welcome to Encore!`;
};

We'll use jQuery to print this message on the page. Install it via:

1
$ yarn add jquery --dev

Great! Use require() to import jquery and greet.js:

1
2
3
4
5
6
7
8
9
10
11
12
// assets/js/app.js

// loads the jquery package from node_modules
const $ = require('jquery');

// import the function from greet.js (the .js extension is optional)
// ./ (or ../) means to look for a local file
var greet = require('./greet');

$(document).ready(function() {
    $('body').prepend('<h1>'+greet('john')+'</h1>');
});

That's it! When you build your assets, jQuery and greet.js will automatically be added to the output file (app.js). For common libraries like jQuery, you may want to create a shared entry for better performance.

Multiple JavaScript Entries

The previous example is the best way to deal with SPA (Single Page Applications) and very simple applications. However, as your app grows, you may want to have page-specific JavaScript or CSS (e.g. homepage, blog, store, etc.). To handle this, add a new "entry" for each page that needs custom JavaScript or CSS:

1
2
3
4
5
6
Encore
    // ...
    .addEntry('homepage', './assets/js/homepage.js')
    .addEntry('blog', './assets/js/blog.js')
    .addEntry('store', './assets/js/store.js')
;

If those entries include CSS/Sass files (e.g. homepage.js requires assets/css/homepage.scss), two files will be generated for each: (e.g. build/homepage.js and build/homepage.css).

Keep Going!

Go back to the List of Encore Articles to learn more and add new features.

This work, including the code samples, is licensed under a Creative Commons BY-SA 3.0 license.
TOC
    Version
    Version:
    Measure & Improve Symfony Code Performance

    Measure & Improve Symfony Code Performance

    Be trained by SensioLabs experts (2 to 6 day sessions -- French or English).

    Be trained by SensioLabs experts (2 to 6 day sessions -- French or English).