README

This is a Laravel template I use for my own projects.

How is it different from a clean Laravel installation ?

The most important change is that it removes all of Laravel Mix configuration and adds new webpack config files. I tried using Laravel Mix for some projects but it just didn't feel right. I didn't like how everything was configured, it took way too long to compile sometimes and I just felt like I had no control.

I took the new configuration files from the vue-webpack template and integrated them with Laravel. The workflow feels very nice and fast now.

I also rewrote all the views (even the ones generated by the Auth command) in Vue. The blade templates only define a mount point that maps automatically to a Vue component of the same name defined in the resources/assets/js/pages folder. I will explain more about this in a section below.

At the end there is a lot going on and it's really opinionated, but you can see all of the configuration files and change them if you need to. Or maybe you could just give it a try as it is and tell me what you think!

How can I start a project using this ?

It's really easy to get up and running. Just follow these steps:

Start a project by running composer create-project --prefer-dist prwlr/laravue project-name.
Go into your project directory and run yarn or npm install to install all dependencies.
In your .env file there is a line that reads APP_URL=http://localhost. Change that variable to whatever your application url is. This is important for development since paths to assets will be constructed using this url. For example for the homestead default url it would look like APP_URL=http://homestead.app. If you app is running in a specific port just put it as it is, for example if your app is running on localhost at port 8000, just put APP_URL=http://localhost:8000.
Now you may run yarn dev or npm run dev to start working on your project.

The command will try to open a browser automatically pointing to your project's url. Sometimes it won't be able to, for example when running with vagrant, so just open it manually.

You can also use the php artisan make:auth command which I modified to generate the same pages you would expect, but showcasing some Vue components instead.

About the Libraries

I'll try to list everything that has been included in the template.

Vue components can be written either using JSX syntax via .js files or using .vue files. I prefer the JSX syntax since I feel I have more control. It also feels more natural since I've been writing React for quite a while. If you want to use .vue files syntax, you will have to mount the components yourself. I will add automatic mounting of those later on.
SCSS is used to handle the base styles, variables, mixins and importing and overriding vendors.
Each Vue Component imports an .scssm file to handle its own styles. This file extension was defined by me to tell webpack to process this file with SCSS and CSS Modules. It's a nice combo since you have scoped selectors, and can also make use of your variables and mixins importing them from your sass folder.
Bulma has been imported instead of Bootstrap to handle some styles. Bulma It's more modern, it's completely independant from jQuery or Javascript in general, and you can easily integrate its components with Vue for example. You can remove it or just pull in the components you need since it's very modular. The views generated by the Auth command are using it though so just keep that in mind. There is also an example on how to override its variables.
Normalize.css is imported before any other css to handle some resets.
Animate.css was also included in the project. With this it's simple to add animations to some Bulma components or to your own stuff.

What tasks can I use ?

I'll just copy most of the descriptions from the Vuejs Webpack template since this is the template I merged with Laravel. If you want to know anything else about the tasks, about the folder structure or how to change or extend anything refer to their docs.

yarn dev || npm run dev: First-in-class development experience.
- Start developing by going into your browser and hitting your APP_URL (It will try to open it automatically).
- Vue preset to handle vue files written with JSX. This is the syntax I prefer since it's more powerful although a little bit more verbose.
- Webpack + vue-loader for single file Vue components is also available.
- Hot-reloading (It can't preserve the state though).
- State preserving compilation error overlay.
- Lint-on-save with ESLint.
- Source maps.
yarn build || npm run build: Production ready build.
- JavaScript minified with UglifyJS.
- HTML minified with html-minifier.
- CSS across all components extracted into a single file and minified with cssnano.
- All static assets compiled with version hashes for efficient long-term caching, and a production base.blade.php is auto-generated with proper URLs to these generated assets.

There is a command for testing which is yarn test || npm run test, but it doesn't work for now. Still not sure how to handle testing for Vue Components using the JSX syntax. You can consider it WIP.

Configuration options

There is a folder called client_config which has some objects needed for the build and dev configurations. Most of them you don't need to worry about, but there are some that could be useful. For example you can set cssSourceMap to true to generate source maps in development. Is not activated by default because relative paths are "buggy" (A more detailed explanation can be found in a comment in the file). To know more about the options refer to the vuejs-templates webpack docs.

In the .env file you can also set a the DEV_POLLING to TRUE in order to enable polling in the webpack dev config. This is useful when running the project with Homestead for example.

You can also change the DEV_PORT variable in order to change the port in which express will be running (Express is used along with webpack to serve the assets).

Notes

Laravel adds some useful stuff to a global Javascript variable called Laravel. I added some more stuff to it like the error bag and the old inputs. There is an utils folder where I created a file called laravel that just pulls in the global variable and exports it. Then in my Vue components I can import it to make calls to that variable a little bit cleaner.

If a view has an specific requirement for a php variable or something that it could get from Laravel, I have created some little blade files that I put in the resources/views/injectors folder that serve that purpose. They just add a script that attaches the new value to the Laravel global variable. You can then include this injector in the view that should use it. You can check some examples in the views that come by default or in the views generated by the Auth command.

Since I'm using Vue to handle all the content of the views, I've defined a new category of components called page components. You can find them in the resources/assets/js/pages folder. These components are used as the main entry points. There is a convention for connecting pages with views. All page components are created using folders with names written in Pascal Case and map automatically to a mount point or div with an id of the same value as the name of the folder but written in Kebab Case. For example resources/assets/js/pages/ExampleTest/index.js will mount automatically inside <div id="example-test"></div>.

So, anything else ?

Not really. I'd just want to thank you for giving it a try or at least reading through. If you have any feedback it'd be greatly appreciated. I bet a lot of things could be improved and I'm open to discussion, so open an issue, send a pull request or message me to gianluca.prwlr@gmail.com.

prwlr / laravue

Maintainers

Details