Hybridly

Appearance

On this page

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.

bash
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 ​

bash
composer require hybridly/laravel
php artisan hybridly:install

Create root.blade.php in resources/application ​

blade
<!-- 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 ​

shell
npm install hybridly vue axios -D

Configure Vite ​

Rename vite.config.js to vite.config.ts, and register hybridly/vite as a plugin.

ts
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:

ts
import { initializeHybridly } from 'virtual:hybridly/config'

initializeHybridly()

Use enhanceVue to register plugins, components or directives.

Add a tsconfig.json ​

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 ​

bash
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.

bash
pnpm install
open http://hybridly-app.test

At this point, you probably want to initialize your repository and create a first commit.

bash
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.

bash
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.

blade
<!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.

bash
npm install hybridly vue axios -D

At this point, your package.json should look like the following:

json
{
		"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.

ts
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:

ts
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 import.meta 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:

json
{
	"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.

vue
<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.

php
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.

shell
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!