Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
2 contributors

Users who have contributed to this file

@anyt @EugeneC
171 lines (128 sloc) 6.04 KB

Table of Contents

Architecture

Under the hood oro:assets:build command uses webpack to build assets.

The application contains webpack.config.js file that generates webpack configuration using webpack-config-builder.

Webpack entry points with list of files are loaded from assets.yml files from all enabled Symfony bundles according to the bundles load priority.

To see the list of loaded bundles ordered by the priority, run:

php bin/console debug:container --parameter=kernel.bundles --format=json

Note: Entry point - is a group of assets that are loaded together, usually they are merged to a single file.

Usage

Build assets

First, run the php bin/console assets:install --symlink command to symlink all assets' source files to public/bundles/ directory.

Next, run the oro:assets:build command to build assets with the webpack. During the first run it installs npm dependencies required for the build.

Load SCSS or CSS files from the bundle

Create an assets.yml file that contains an entry point list with the files to load.

css:                                                    # Entry point name. 
    inputs:                                             # List of files to load for `css` entry point
        - 'bundles/app/css/scss/main.scss'
    # You do not need to provide output for this entry point, it is already defined in 
    # vendor/oro/platform/src/Oro/Bundle/UIBundle/Resources/config/oro/assets.yml            
checkout:                                               # Another entry point name
    inputs:                                             # List of files to load for `checkout` entry point
        - 'bundles/app/scss/checkout_page_styles.scss'
    output: 'css/checkout-styles.css'                   # Output file path inside public/ directory for the `checkout` entry point

Location of assets.yml file

Management Console [BUNDLE_NAME]/Resources/config/oro/assets.yml
Store Front [BUNDLE_NAME]/Resources/views/layouts/[THEME_NAME]/config/assets.yml

Default entry points and output file names

entry point name output file
Management Console css css/themes/oro/oro.css
Store Front styles css/layout/[THEME_NAME]/styles.css

Note: SCSS is the recommended format, CSS format is deprecated by sass-loader npm module.

Commands

oro:assets:build command

The command runs webpack to build assets.

In dev environment command builds assets without minification and with source maps. In prod environment assets are minified and do not include source maps.

Note: When using the watch mode after changing the assets configuration at assets.yml files, it is required to restart the command, otherwise it will not detect the changes.

Usage

  • oro:assets:build [-w|--watch] [-i|--npm-install] [--] [<theme>]
  • oro:assets:build admin.oro to build assets only for default management-console theme, named admin.oro
  • oro:assets:build default --watch to build assets only for blank theme with enabled watch mode

Arguments

theme

Theme name to build. When not provided, all available themes are built.

Options

--watch|-w

Turn on watch mode. This means that after the initial build, webpack continues to watch the changes in any of the resolved files.

--npm-install|-i

Reinstall npm dependencies to vendor/oro/platform/build folder, to be used by webpack. Required when node_modules folder is absent or corrupted.

Configuration reference

AssetBundle defines configuration for NodeJs and NPM executable.

All these options are configured under the oro_asset key in your application configuration.

# displays the default config values defined by Oro
 php bin/console config:dump-reference oro_asset
# displays the actual config values used by your application
 php bin/console debug:config oro_asset

Configuration

nodejs_path

type: string required, default: found dynamically

Path to NodeJs executable.

npm_path

type: string required, default: found dynamically

Path to NPM executable.

build_timeout

type: integer required, default: 300

Assets build timeout in seconds, null to disable timeout.

npm_install_timeout

type: integer required, default: 900

Npm installation timeout in seconds, null to disable timeout.

Troubleshooting

Error: Node Sass does not yet support your current environment

After the update of NodeJs you might experience an error because node modules were built on the old NodeJs version that is not compatible with the new one.

To fix the error, remove the existing node modules and re-build the assets:

rm -rf vendor/oro/platform/build/node_modules
php bin/console cache:clear
php bin/console oro:assets:build

JS engine not found

Appears when configuration in cache is broken.

To fix the error, remove an application cache and warm it up:

rm -rf var/cache/*
php bin/console cache:warmup

Error: "output" for "assets" group in theme "oro" is not defined

Please follow upgrade documentation to update assets.yml files according to new requirements.

You can’t perform that action at this time.