Installation
Hybridly consists of a Laravel adapter, a Vue adapter and a Vite plugin. These last two are distributed together in the hybridly
npm package.
You may install Hybridly in a fresh Laravel project using the preset. If you prefer, you can proceed to a manual installation. Alternatively, you can follow a detailed installation guide.
Preset
The recommended way of installing Hybridly is to create a fresh Laravel project and use the preset.
composer create-project laravel/laravel my-project
cd my-project
npx @preset/cli apply hybridly/preset
This will configure Tailwind CSS, Pest, and optionally internationalization through vue-i18n
. More information about the options on the repository.
Server-side setup
This section is a summary of what's needed server-side, so that you can conveniently copy-paste snippets. For more thorough explanations, follow the detailed guide.
Install the Laravel package
composer require hybridly/laravel
php artisan hybridly:install
Create root.blade.php
in resources/application
<!-- resources/application/root.blade.php -->
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
@vite(['resources/css/app.css', 'resources/application/main.ts'])
</head>
<body class="antialiased">
@hybridly
</body>
</html>
Client-side setup
This section is a summary of what's needed client-side, so that you can conveniently copy-paste snippets. For more thorough explanations, follow the detailed guide.
Install the dependencies
npm install hybridly vue axios -D
Configure Vite
Rename vite.config.js
to vite.config.ts
, and register hybridly/vite
as a plugin.
import { defineConfig } from 'vite'
import hybridly from 'hybridly/vite'
export default defineConfig({
plugins: [
hybridly({
laravel: {
valetTls: true
}
}),
],
})
Initialize Hybridly
Delete the resources/js
directory, and create a resources/application/main.ts
file with the following snippet:
import { initializeHybridly } from 'virtual:hybridly/config'
initializeHybridly()
Use enhanceVue
to register plugins, components or directives.
Add a tsconfig.json
{
"extends": "./.hybridly/tsconfig.json"
}
Detailed installation guide
This little guide assumes you are using macOS with Laravel Valet.
Create and cd
into the project
composer create-project laravel/laravel hybridly-app
cd hybridly-app
Install Node dependencies and navigate to hybridly-app.test
to ensure the default installation is working properly.
pnpm install
open http://hybridly-app.test
At this point, you probably want to initialize your repository and create a first commit.
git init
git add .
git commit -m "chore: initialize project"
Install the Laravel adapter
The first step is to install the Laravel adapter and setup the middleware.
composer require hybridly/laravel
php artisan hybridly:install
The last command extracted the middleware that is required to intercept responses and convert them to the Hybridly protocol.
That middleware is, by default, located in app/Http/Middleware/HandleHybridRequests.php
. It has automatically been registered into the web
middleware group in app/Http/Kernel.php
.
Create root.blade.php
Hybridly needs a root.blade.php
file that will be loaded on the first page render. The name and path are configurable, but it's a good default.
Proceed to delete resources/views
, and create resources/application/root.blade.php
. It needs to contain the @hybridly
directive and to load assets.
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
@vite(['resources/css/app.css', 'resources/application/main.ts'])
</head>
<body class="antialiased">
@hybridly
</body>
</html>
Install the Vite plugin
The next step is to install and register the Vite plugin. It is, along with the Vue adapter, distributed in the hybridly
package on npm.
We also need to install Vue and the latest version of Axios.
npm install hybridly vue axios -D
At this point, your package.json
should look like the following:
{
"private": true,
"scripts": {
"dev": "vite",
"build": "vite build"
},
"devDependencies": {
"axios": "^1.3.0",
"hybridly": "0.0.1-alpha.21",
"lodash": "^4.17.19",
"postcss": "^8.1.14",
"vite": "^4.1.2",
"vue": "^3.2.41"
}
}
Now is a good time to rename vite.config.js
to vite.config.ts
and register the hybridly
plugin, exported by hybridly/vite
.
import { defineConfig } from 'vite'
import hybridly from 'hybridly/vite'
export default defineConfig({
plugins: [
hybridly({
laravel: {
valetTls: true
}
}),
],
})
If you add valetTls
, which you should, don't forget to also run valet secure
and set up APP_URL
in .env
.
Initialize Hybridly
The Vite part is done, now you need to make your scripts aware of Hybridly. Delete the resources/js
directory and create resources/application/main.ts
, which should contain the following snippet:
import { createApp } from 'vue'
import { initializeHybridly } from 'virtual:hybridly/config'
initializeHybridly({
enhanceVue: (vue) => {}
})
You can read more about initializeHybridly
in the API documentation.
Add a tsconfig.json
Your project needs a tsconfig.json
file to understand objects such as i
or imports like virtual:hybridly/config
. The complicated part of this file is automatically generated by Hybridly when the development server is started, so you can create your own simple tsconfig.json
that extends it:
{
"extends": "./.hybridly/tsconfig.json"
}
The TypeScript documentation is a good place to understand the configuration options that are available in this file.
Create a page component
It's almost done. We just need a page component and a route to serve it. Create a resources/views/pages/index.vue
file. A page component is a standard Vue component, except it's now a page component.
<script setup lang="ts">
//
</script>
<template>
<div>
Hello Hybridly
</div>
</template>
Create a route
In routes/web.php
, you can now instruct a route to load your new page component. You just need to give its name to the hybridly
function.
Route::get('/', function () {
return hybridly('index');
});
Start the development server
That's it. You only need to run npm run dev
and open the application in your browser.
npm run dev
open https://hybridly-app.test
A preset is available
If you found that installation process tedious, consider using the preset for your next project.
What's next?
Hybridly has many features. You probably want to know how to pass data from the server to the front-end or how to navigate between pages.
Feel free to explore the whole documentation before committing to Hybridly. Have fun building your applications!