# CardsChat’s New Asset Pipeline

### Couple of commands to remember
`cc npm run build:development` runs the development build without any optimization.

`cc npm run build:production` runs the production build with optimizations.

(I'll add more if needed once these commands are set in stone)

### Why?
The current asset pipeline is very outdated. The structure of our asset folder is unsustainable and it will become more and more difficult to contribute to the codebase especially for new devs. We need a better way.

### Is there something you don't like in this docs?
If you would you like to change something in the docs or the way this new implementation works please let us know. We're all ears and open minded!!

### How did it work before?
The asset folders in `Sources` folder are copied over to their appropriate folder located in CardsChat’s root. The content (the files) in these folders are optimised.

`/Sources/PKimg` -> `/pkimg`
`/Sources/Images` -> `/images`
`/Sources/Images_fb` -> `/images_fb`
`/Sources/Css` -> `/styles`
`/Sources/Js` -> `/js`

### What’s changed?
It is still using Gulp to copy and optimise the files from these folders. Gulp was upgraded to v4 from v3, further optimisations were added and some of the plugins were replaced by newer and better alternatives. Conditionals were added so that optimization of the files only happens during a production build. (bitOptimisation is ignored during development as it’s a waste of time.)

Webpack was added to help with SASS compilation and ES6 transpiling but it also introduced features like Linting, Autoprefixing, Tree Shaking, Code Splitting, Asset Versioning & Cache Busting and many more.

A new folder (`ComponentLibrary` ) was created in `Sources`. This is where we can use SASS language and next generation Javascript. The structure of this folder is quite different compared to the other ones. Some might find similarities in the structures to a 7-1 pattern.

The goal was not to just have another asset folder but to create an architecture that is sustainable and modular. In this folder code is decoupled and separated into individual pieces but in a way that Webpack can easily generate a dependency graph and only use code that is actually needed.

### What is what in ComponentLibrary?

`00-abstract` folder should only contain SCSS code but when it is compiled it should never output any CSS. It gathers all SASS tools and helpers used across the project.
e.g.: global mixins, placeholders, functions and such..

`01-base` folder should contain the minimal but common/shared CSS and Javascript that must be loaded on every individual page.
e.g: grid, or container

`02-components` folder should contain the actual components that are being used on the website. Right now there is no further separation by the size of component but we can easily integrate Atomic Design System or something else.
e.g.: button—yellow, toplist, slider

`03-layout` folder should contain everything that takes part in laying out the site or application. (the main parts of the site)
e.g.: versions of the footer, header, navigation and maybe sidebar.

`04-templates` folder should contain code for templates that are extended by pages. Those pages could very much look the same or very similar to each other, therefore sharing the code that is common. I guess we will have to be very innovative here coming up with template names.
e.g.: casino-reviews

`05-pages` folder should contain the code for the individual pages. It usually builds on top of a common template. It inherits all the dependencies of a template. This is an *entry point*.
e.g.: bitcoin-casinos, blackjack

`06-inbound` folder should contain the marketing pieces only. These are small “websites” on their own looking nothing like CardsChat but they could share dependencies and libraries with the rest. This is an *entry point*.
e.g.: ebook

### What does entry point mean?
Each JS file is set as an entry point in `05-pages` and `06-inbound` folders. The entry point defines all the dependency of a particular webpage, so we are telling webpack that we would like separate dependency graphs.

In a multi-page application, the server is going to fetch a new HTML document for you. The page reloads this new document and assets are redownloaded. However, this gives us the unique opportunity to do things like using [optimization.splitChunks](https://webpack.js.org/configuration/optimization/#optimizationsplitchunks) to create bundles of shared application code between each page. Multi-page applications that reuse a lot of code/modules between entry points can greatly benefit from these techniques, as the number of entry points increases.

### How does this work in real life?
Let’s navigate to https://www.cardschat.com/deposit/bitcoin-casinos/. This page is using a WebTemplate named `bitcoin-casinos` . There is an entry point called `bitcoin-casinos` created and it defines all its dependencies in one place. (in `bitcoin-casinos.js` file). Webpack will take care of including and sorting out the code in an effective way. The `bitcoin-casinos` WebTemplate will load all its dependencies defined in `05-pages/bicoin-casinos/bitcoin-casinos.js` .

All the dependencies are processed and copied over to the distribution folder. We don’t have to know the path nor the exact filenames of the processed files as webpack’s resolver takes care of everything.

#### Stylesheets
The entry point could import a `.scss` file, this will be extracted out of javascript by webpack during the build time and a separate (hashed) `.css` file will be loaded by the page.

e.g.:
`import './bitcoin-casinos.scss'` will import the file from the very same directory.

#### Images
The entry point itself (`.js` file) or that (`.scss`) file could import OR link to an image which will be extracted out and optimised and hashed accordingly. The url will be resolved and replaced by webpack too. (I’d recommend creating an asset folder and including everything else there)

e.g:

If you want to work with the image in javascript you can do:
`import Image from'./assets/some-image.png'`;

Access the the final path in the distribution folder like this:
`console.log(Image.src)`

If `.scss` file contains an url to an image the following happens:
`background: url('./assets/some-image.png')`

This image will be processed by webpack, copied to the distribution folder and the path will be resolved. The final `.css` file in the distribution folder will contain the correct path to the final image.

#### Javascript
If you import another javascript file from the entrypoint, such as a template or a component. That javascript file will be processed the very same way as described above. These javascript files should be ES Modules and imported in a modern way. `(import click from './click.js')`.

It also means that each of these modules will have their own dependencies (assets) processed and sorted/optimized the best way it’s possible by webpack.

You can also code normal Javascript in the entry points itself and it will be loaded only on that single page.

Writing `console.log('Hello!')` to `05-pages/bitcoin-casinos/bitcoin-casinos.js` will output `Hello!` in the Chrome’s console when `bitcoin-casinos` page is loaded.

Writing `console.log('Hello!')` to `04-templates/casino-reviews/casino-reviews.js` will output `Hello!` in the Chrome’s console when pages are loaded using `04-templates/casino-reviews/casino-reviews.js` template.

*Don’t confuse `templates` in `ComponentLibrary` with Logician Templates. Logician Templates are pretty much pages but the terminology/wording is wrong.*

#### What about other referenced assets in HTML?
Wepack works best with Single Page Applications (SPA) built with Javascript. CardsChat is not that and I doubt it will every be, it is a Multi Page Application (MPA) built with PHP.

In an SPA world, HTML generation is done by Javascript and as we could see Webpack can easily resolve references to asset files.

Unfortunately, there is no easy solution for url resolution by Webpack in MPAs. Therefore, referencing asset files in HTML will not change. When a `<img>` html tag is used, the `src` attribute must point to the image in the appropriate distribution folder (not in Sources).

The `ComponentLibrary` folder should not be used to store assets that are referenced from the HTML. Versioning is enabled for all asset files in `ComponentLibrary` and as the filename could change, therefore it is not recommended to reference them (hard-code the path) from HTML.

e.g.:
In `bitcoin-casinos` WebTemplate we should use the following:
`<img src="/pkimg/another-image.jpg">`

`another-image.jpg` should be placed in `Sources/PKimg`, which will be handled by Gulp as usual.

### Why are we still keeping the old asset folders?

We have to keep the folders in `Sources` as it would be impossible to do an overnight “migration”. The old code will continue to be there so that we can transition gradually.

### What about the new requests to assets that are added to our pages?

I guess we have compromise a little bit. I hope that we slowly start reducing the legacy code that we actually need for each page. This will eventually speed things up and we will never have to manage dependencies the way we managed before.