From f68753d2ea0434ab33e3d8325e92719cb71d4c95 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Fri, 28 Dec 2018 17:54:55 +0100 Subject: [PATCH 1/3] Merge all Encore installation articles into a single one --- _build/redirection_map | 1 + frontend/encore/installation-no-flex.rst | 113 -------------------- frontend/encore/installation.rst | 126 +++++++++++++++++++++-- 3 files changed, 118 insertions(+), 122 deletions(-) delete mode 100644 frontend/encore/installation-no-flex.rst diff --git a/_build/redirection_map b/_build/redirection_map index f503603e160..b05f315c246 100644 --- a/_build/redirection_map +++ b/_build/redirection_map @@ -358,3 +358,4 @@ /service_container/service_locators /service_container/service_subscribers_locators /weblink /web_link /components/weblink /components/web_link +/frontend/encore/installation-no-flex /frontend/encore/installation diff --git a/frontend/encore/installation-no-flex.rst b/frontend/encore/installation-no-flex.rst deleted file mode 100644 index 22d16c58e01..00000000000 --- a/frontend/encore/installation-no-flex.rst +++ /dev/null @@ -1,113 +0,0 @@ -Encore Installation (without Symfony Flex) -========================================== - -.. tip:: - - If your project uses Symfony Flex, read :doc:`/frontend/encore/installation` - for easier instructions. - -Installing Encore ------------------ - -Install Encore into your project via Yarn: - -.. code-block:: terminal - - $ yarn add @symfony/webpack-encore --dev - -.. note:: - - If you prefer to use `npm`_, no problem! Run ``npm install @symfony/webpack-encore --save-dev``. - -This command creates (or modifies) a ``package.json`` file and downloads dependencies -into a ``node_modules/`` directory. Yarn also creates/updates a ``yarn.lock`` -(called ``package-lock.json`` if you use npm version 5+). - -.. tip:: - - You *should* commit ``package.json`` and ``yarn.lock`` (or ``package-lock.json`` - if using npm 5) to version control, but ignore ``node_modules/``. - -Creating the webpack.config.js File ------------------------------------ - -Next, create a new ``webpack.config.js`` file at the root of your project: - -.. code-block:: js - - var Encore = require('@symfony/webpack-encore'); - - Encore - // directory where compiled assets will be stored - .setOutputPath('web/build/') - // public path used by the web server to access the output path - .setPublicPath('/build') - // only needed for CDN's or sub-directory deploy - //.setManifestKeyPrefix('build/') - - /* - * ENTRY CONFIG - * - * Add 1 entry for each "page" of your app - * (including one that's included on every page - e.g. "app") - * - * Each entry will result in one JavaScript file (e.g. app.js) - * and one CSS file (e.g. app.css) if you JavaScript imports CSS. - */ - .addEntry('app', './assets/js/app.js') - //.addEntry('page1', './assets/js/page1.js') - //.addEntry('page2', './assets/js/page2.js') - - // will require an extra script tag for runtime.js - // but, you probably want this, unless you're building a single-page app - .enableSingleRuntimeChunk() - - .cleanupOutputBeforeBuild() - .enableSourceMaps(!Encore.isProduction()) - // enables hashed filenames (e.g. app.abc123.css) - .enableVersioning(Encore.isProduction()) - - // uncomment if you use TypeScript - //.enableTypeScriptLoader() - - // uncomment if you use Sass/SCSS files - //.enableSassLoader() - - // uncomment if you're having problems with a jQuery plugin - //.autoProvidejQuery() - ; - - module.exports = Encore.getWebpackConfig(); - -Next, create a new ``assets/js/app.js`` file with some basic JavaScript *and* -import some JavaScript: - -.. code-block:: javascript - - // assets/js/app.js - - require('../css/app.css'); - - console.log('Hello Webpack Encore'); - -And the new ``assets/css/app.css`` file: - -.. code-block:: css - - /* assets/css/app.css */ - body { - background-color: lightgray; - } - -You'll customize and learn more about these file in :doc:`/frontend/encore/simple-example`. - -.. caution:: - - Some of the documentation will use features that are specific to Symfony or - Symfony's `WebpackEncoreBundle`_. These are optional, and are special ways of - pointing to the asset paths generated by Encore that enable features like - :doc:`versioning ` and - :doc:`split chunks `. - -.. _`npm`: https://www.npmjs.com/ -.. _WebpackEncoreBundle: https://github.com/symfony/webpack-encore-bundle diff --git a/frontend/encore/installation.rst b/frontend/encore/installation.rst index 4061691153b..8598342e9e8 100644 --- a/frontend/encore/installation.rst +++ b/frontend/encore/installation.rst @@ -1,22 +1,130 @@ -Installing Encore (with Symfony Flex) -===================================== +Installing Encore +================= -.. tip:: +First, make sure you `install Node.js`_ and also the `Yarn package manager`_. +The following instructions depend on whether you are installing Encore in a +Symfony application or nor. - If your project does **not** use Symfony Flex, read :doc:`/frontend/encore/installation-no-flex`. +Installing Encore in Symfony Applications +----------------------------------------- -First, make sure you `install Node.js`_ and also the `Yarn package manager`_. Then -run: +In your application is using :doc:`Symfony Flex `, run the +following commands. Otherwise, skip to the next section: .. code-block:: terminal $ composer require encore $ yarn install -This will create a ``webpack.config.js`` file, add the ``assets/`` directory, and -add ``node_modules/`` to ``.gitignore``. +This will create a ``webpack.config.js`` file, add the ``assets/`` directory, +and add ``node_modules/`` to ``.gitignore``. + +Nice work! You can skip the rest of this article and go write your first +JavaScript and CSS by reading :doc:`/frontend/encore/simple-example`! + +Installing Encore in non Symfony Applications +--------------------------------------------- + +Install Encore into your project via Yarn: + +.. code-block:: terminal + + $ yarn add @symfony/webpack-encore --dev + + # if you prefer npm, run this command instead: + # npm install @symfony/webpack-encore --save-dev + +This command creates (or modifies) a ``package.json`` file and downloads +dependencies into a ``node_modules/`` directory. Yarn also creates/updates a +``yarn.lock`` (called ``package-lock.json`` if you use npm). + +.. tip:: + + You *should* commit ``package.json`` and ``yarn.lock`` (or ``package-lock.json`` + if using npm) to version control, but ignore ``node_modules/``. + +Creating the webpack.config.js File +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Next, create a new ``webpack.config.js`` file at the root of your project: + +.. code-block:: js + + var Encore = require('@symfony/webpack-encore'); + + Encore + // directory where compiled assets will be stored + .setOutputPath('web/build/') + // public path used by the web server to access the output path + .setPublicPath('/build') + // only needed for CDN's or sub-directory deploy + //.setManifestKeyPrefix('build/') + + /* + * ENTRY CONFIG + * + * Add 1 entry for each "page" of your app + * (including one that's included on every page - e.g. "app") + * + * Each entry will result in one JavaScript file (e.g. app.js) + * and one CSS file (e.g. app.css) if you JavaScript imports CSS. + */ + .addEntry('app', './assets/js/app.js') + //.addEntry('page1', './assets/js/page1.js') + //.addEntry('page2', './assets/js/page2.js') + + // will require an extra script tag for runtime.js + // but, you probably want this, unless you're building a single-page app + .enableSingleRuntimeChunk() + + .cleanupOutputBeforeBuild() + .enableSourceMaps(!Encore.isProduction()) + // enables hashed filenames (e.g. app.abc123.css) + .enableVersioning(Encore.isProduction()) + + // uncomment if you use TypeScript + //.enableTypeScriptLoader() + + // uncomment if you use Sass/SCSS files + //.enableSassLoader() + + // uncomment if you're having problems with a jQuery plugin + //.autoProvidejQuery() + ; + + module.exports = Encore.getWebpackConfig(); + +Next, create a new ``assets/js/app.js`` file with some basic JavaScript *and* +import some JavaScript: + +.. code-block:: javascript + + // assets/js/app.js + + require('../css/app.css'); + + console.log('Hello Webpack Encore'); + +And the new ``assets/css/app.css`` file: + +.. code-block:: css + + /* assets/css/app.css */ + body { + background-color: lightgray; + } + +You'll customize and learn more about these file in :doc:`/frontend/encore/simple-example`. + +.. caution:: -Nice work! Write your first JavaScript and CSS by reading :doc:`/frontend/encore/simple-example`! + Some of the documentation will use features that are specific to Symfony or + Symfony's `WebpackEncoreBundle`_. These are optional, and are special ways of + pointing to the asset paths generated by Encore that enable features like + :doc:`versioning ` and + :doc:`split chunks `. .. _`install Node.js`: https://nodejs.org/en/download/ .. _`Yarn package manager`: https://yarnpkg.com/lang/en/docs/install/ +.. _`npm`: https://www.npmjs.com/ +.. _`WebpackEncoreBundle`: https://github.com/symfony/webpack-encore-bundle From d1f0c8f2be93d6468da55567b0673f76bd01afe3 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Fri, 28 Dec 2018 17:58:43 +0100 Subject: [PATCH 2/3] - --- frontend/encore/installation.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/frontend/encore/installation.rst b/frontend/encore/installation.rst index 8598342e9e8..d95c9640705 100644 --- a/frontend/encore/installation.rst +++ b/frontend/encore/installation.rst @@ -3,7 +3,7 @@ Installing Encore First, make sure you `install Node.js`_ and also the `Yarn package manager`_. The following instructions depend on whether you are installing Encore in a -Symfony application or nor. +Symfony application or not. Installing Encore in Symfony Applications ----------------------------------------- From 284fae56306aa9c2cad9ae6be41d9de3e1064a97 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Sun, 30 Dec 2018 11:11:17 +0100 Subject: [PATCH 3/3] Rewords --- frontend/encore/installation.rst | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/frontend/encore/installation.rst b/frontend/encore/installation.rst index d95c9640705..dba811ec232 100644 --- a/frontend/encore/installation.rst +++ b/frontend/encore/installation.rst @@ -8,16 +8,18 @@ Symfony application or not. Installing Encore in Symfony Applications ----------------------------------------- -In your application is using :doc:`Symfony Flex `, run the -following commands. Otherwise, skip to the next section: +If your application is using :doc:`Symfony Flex `, run the +following commands: .. code-block:: terminal $ composer require encore $ yarn install -This will create a ``webpack.config.js`` file, add the ``assets/`` directory, -and add ``node_modules/`` to ``.gitignore``. +This will install and enable the `WebpackEncoreBundle`_, add the ``assets/`` +directory, create a ``webpack.config.js`` file, and add ``node_modules/`` to +``.gitignore``. If you are not using Symfony Flex, you'll need to create all +this by yourself following the instructions shown in the next section. Nice work! You can skip the rest of this article and go write your first JavaScript and CSS by reading :doc:`/frontend/encore/simple-example`! @@ -46,7 +48,8 @@ dependencies into a ``node_modules/`` directory. Yarn also creates/updates a Creating the webpack.config.js File ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Next, create a new ``webpack.config.js`` file at the root of your project: +Next, create a new ``webpack.config.js`` file at the root of your project. This +is the main config file for both Webpack and Webpack Encore: .. code-block:: js @@ -119,8 +122,8 @@ You'll customize and learn more about these file in :doc:`/frontend/encore/simpl .. caution:: Some of the documentation will use features that are specific to Symfony or - Symfony's `WebpackEncoreBundle`_. These are optional, and are special ways of - pointing to the asset paths generated by Encore that enable features like + Symfony's `WebpackEncoreBundle`_. These are optional, and are special ways + of pointing to the asset paths generated by Encore that enable features like :doc:`versioning ` and :doc:`split chunks `.