js/ directory directly under our public document root directory. Then the URL is simply
http://example.com/js/whatever.js, and our webserver matches the URL path
/js/whatever.js to the filesystem path
/path/to/document/root/js/whatever.js, and places the contents of that file in the HTTP response. In most web servers this happens so transparently, that a lot of new developers assume that they're somehow giving direct access to the server's file system. In reality the web server is mediating the interaction, and generating an HTTP response using the contents of these files.
In UserFrosting, the Sprinkle system makes this a little more complicated. Each Sprinkle can contribute its own assets to the application (under its
assets/ subdirectory), and it should be possible for a Sprinkle to override assets in another Sprinkle that was loaded earlier in the stack.
Configuring the web server to handle all of the extra logic would be tedious, error-prone, and could easily introduce security risks. For these reasons, UserFrosting has the ability to serve assets through the application, rather than relying on the web server to handle these requests directly.
You may be thinking "won't raw assets add a lot of overhead and slow down my application?" If so, you would be absolutely, 100% correct. This is why raw assets are only meant to be used in development. When you're ready to deploy your application to the live server, one of the tasks that must be done is to compile your assets and asset bundles.
Compiling assets basically does three main things:
To compile assets for a production environment, simply use the Bakery CLI tool:
$ php bakery build-assets --compile
If you have shell access (for example, using a VPS), you can run this directly on your host server as part of your deployment process. Otherwise, you can run Bakery locally before transferring your application to the host server.
Once the compiled asset files have been generated, we can easily configure the asset manager to substitute the urls for raw assets in our pages with urls for compiled assets. Simply set the configuration value for
false. The default production config file has this already configured for you.
If you reload your page and view the source, you'll see that references to the compiled assets are now being used instead:
<!-- Include main CSS asset bundle --> <link rel="stylesheet" type="text/css" href="http://localhost/myUserFrostingProject/public/assets/css/main-2c1912c984.css" > <!-- Page-group-specific CSS asset bundle --> <link rel="stylesheet" type="text/css" href="http://localhost/myUserFrostingProject/public/assets/css/guest-5a16771b5a.css" >
AssetManager service pulls the names of these compiled assets from
build/bundle.result.json, which was generated when we ran the
Bakery uses a suite of tools based on Node.js to build and compile assets. Fortunately for you, you should already have Node.js installed if you completed the UserFrosting installation process successfully!
Why do we use Node.js, anyway, instead of a PHP-based asset management tools?
Gulp should have been automatically installed for you during the installation process.
All build tasks are defined in
build/gulpfile.js. UserFrosting ships with three preconfigured tasks for building assets:
uf-bundle-build task combines the
asset-bundles.json files in each loaded Sprinkle (as per your
sprinkles.json file), respecting the collision rules defined in each bundle. This combined bundle file is written to
uf-bundle task uses
gulp-bundle-assets to minify and concatenate the assets referenced in each bundle in
build/asset-bundles.json into a single file per bundle. These compiled bundles will be placed in the
public/assets/ directory by default. It also copies fonts, images, and other files from your Sprinkles to the
public/assets/ directory, so that your web server can directly serve these files as well.