Skip to content
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

Add docs about Webpack Encore. #120

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Add docs about Webpack Encore. #120

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
62 changes: 62 additions & 0 deletions source/documentation/basic-project.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -81,6 +81,68 @@ generating the site.
With this option passed, `{{ site.url }}/about` will now be generated as
`http://my.dev.host/blog-skelton/output_dev/about` instead of `/about`.

## CSS and JavaScript

bellisk marked this conversation as resolved.
Show resolved Hide resolved
It is best practice to combine all your CSS files and all your JavaScript files
into single files. That way they are simple to include in your templates and
create less overhead for the browser loading the page. The recommended way to
combine assets is with Symfony's
[Webpack Encore](https://symfony.com/doc/current/frontend.html).

The [Blog Skeleton](https://github.com/sculpin/sculpin-blog-skeleton) project
uses Encore to manage assets. If you're setting up your project with Sculpin
directly, not using the skeleton, install Encore using the
[setup instructions](https://symfony.com/doc/current/frontend/encore/installation.html).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i'd add one more paragraph here saying that you need to install yarn and link to https://yarnpkg.com/en/docs/install for installation instructions

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure that's necessary, as the Encore instructions start off by telling you to install Node and Yarn, and link to the installation docs for both.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The sculpin-blog-skeleton README mentions using yarn to install the JS dependencies, but doesn't talk about installing yarn itself. I think if we are going to mention that anywhere, it should be in that README. @dbu maybe you could add that to sculpin/sculpin-blog-skeleton#61 ?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤦‍♂️ Oh, you included that in sculpin/sculpin-blog-skeleton#61 already, sorry. I still don't think it's necessary to note it separately here.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

k


The rest of this section assumes that you are using Encore, with a
configuration like
[in the skeleton](https://github.com/sculpin/sculpin-blog-skeleton/blob/master/webpack.config.js).

Put your CSS and JS assets in the directory `source/assets/` as shown.

|-- source/
`-- assets/
|-- css/
| `-- app.css
`-- js/
`-- app.js

The app's main CSS file is configured to be `source/assets/css/app.css`.
You can add more CSS files in the same directory if necessary and require them
in your JavaScript files to use them.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

why javascript files? "... and require them in your app.css file to make them included."?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You can do it that way, but the preferred way is really to require them in your javascript files. (It's also possible to add CSS files to webpack.config.js by themselves, but again, not preferred. https://symfony.com/doc/current/frontend/encore/simple-example.html#compiling-only-a-css-file)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

so the css is embedded in javascript? isn't that bad for page loading performance? or how should i understand "require"?


Encore can also support Sass, and the Blog Skeleton is set up to use it. See
the relevant
[Encore docs](https://symfony.com/doc/current/frontend/encore/simple-example.html#using-sass-less-stylus)
for more details.

The app's main JavaScript file is `source/assets/js/app.js`. Make sure that it
is added in the `webpack.config.js` configuration file. You can add further
JavaScript files and require them in `app.js`, and `require` other libraries as
necessary.

Build the assets using the command:

yarn encore dev --watch

Encore will then compile all the CSS into the `build/app.css` file and all the
JavaScript, including library code, into the `build/app.js` file.

The default templates in the skeleton come with the correct stylesheet link and
script tag. If you build your own templates, add these tags to your base
template (in `_views/`):

```html
<head>
<link rel="stylesheet" href="{{ site.url }}/build/app.css">
</head>
<body>
(all your other content)

<script src="{{ site.url }}/build/app.js"></script>
</body>
```

## Environments

Sculpin knows the `dev` and `prod` environment. They allow you to have
Expand Down