💾 О проекте

Данная библиотека разработана для организации SSR в Vite/Vue3 проектах, с минимальными требованиями по архитектуре.

Зачем это нужно?

• Для разработки проектов без ограничений по правилам оформления роутинга, иерархии компонентов и других "палок" в колёсах от других известных реализаций SSR
• Предоставление удобных методов (composables) для префетча данных на стороне сервера

Основная цель проекта: не навязывать собственную архитектуру разработки SSR проекта, а лишь служить удобным дополнением к проектам разработанным на Vite

🗒️ УСТАНОВКА

1. Установка зависимостей (Vue):

pnpm i lite-ssr @unhead/vue 

2. Заменяем createApp на createApp из lite-ssr и экспортируем приложение

import { createApp } from 'lite-ssr'
import './style.css'
import App from './App.vue'

const app = createApp(App)
app.mount('#app');

export default app // Обязательно экспортируем app

Экспортировать приложение требуется для того, чтобы lite-ssr мог использовать один entry-файл для рендера приложения на сервере и клиенте, а так же для проброса префетч-данных между сервером и клиентом.

3. Создание файла конфигурации /lssr.config.ts

// lssr.config.ts
import { defineLssrConfig } from "lite-ssr";

export default defineLssrConfig({
    entry: "/src/main.ts",
    head: {
        title: "LSSR App"
    }
});

4. Добавляем файл конфигурации вtsconfig.node.json

// tsconfig.node.json
{
  ...
  "include": ["lssr.config.ts"]
}

5. Меняем команды запуска и сборки в package.json

{
    "scripts": {
        "dev": "lssr --framework=vue",
        "build": "lssr --framework=vue --build",
        "serve": "lssr --framework=vue --serve",
    },
}

Запуск проекта:

Запуск в dev-режиме:

pnpm run dev

Сборка проекта:

pnpm run build

Запуск проекта в production-режиме:

pnpm run serve

🔎 ИСПОЛЬЗОВАНИЕ

Конфигурация LSSR

// lssr.config.ts
import { defineLssrConfig } from "lite-ssr";

export default defineLssrConfig({
    entry?: "/src/main.ts", // Опционально, путь к файлу инициализации приложения
    head?: { // Опционально, конфигурация unhead (https://unhead.unjs.io/usage/composables/use-head#input)
        title: "My LSSR App"
    },
    html?: "/index.html", // Опционально, путь к кастомному html файлу (пользуйтесь с умом!)
    dist?: "/dist" // Директория для сборки
});

Создание асинхронных сторов

Для организации получения данных на стороне сервера и клиента, библиотека предоставляет возможность создавать префетч-сторы, для упрощения работы с асинхронными запросами

Пример создания стора:

// useData.ts
import { ref } from "vue";
import { definePrefetchStore } from "lite-ssr/vue";

export const useData = definePrefetchStore('data', () => {
    // Инициализация стейтов
    const data = ref<null | any>(null);
    const loading = ref<boolean>(false);
    const error = ref<boolean>(false);

    // Инициализация асинхроных функций
    const fetchData = async (id: number) => {
        loading.value = true;

        const response = await fetch(`https://jsonplaceholder.typicode.com/todos/${id}`);
        
        if (response.ok) {
            data.value = await response.json();
        } else {
            data.value = null;
            error.value = true;
        }

        loading.value = false;
    };

    // Возвращаем стейты и функции
    return {
        data,
        loading,
        error,
        fetchData
    }
})

! ВАЖНАЯ ИНФОРМАЦИЯ !

Префетч-сторы, как и сторы Pinia требуют уникального наименования. Это нужно для правильной передачи информации полученной на стороне SSR клиенту !

Пример использования получившегося стора:

<!--App.vue-->
<template>
    <div>
        <span v-if="loading">Загрузка данных...</span>
        <span v-else-if="error">Не удалось загрузить данные</span>
        <pre v-else>{{ serializedData }}</pre>
    </div>
</template>

<script setup lang="ts">
    import { computed, onMounted } from 'vue'
    import { useData } from "./useData";

    // Подключаем наш стор
    const { fetchData, data, loading, error } = useData(); 

    // Сериализуем данные для удобочитаемости
    const serializedData = computed( 
        () => data ? JSON.stringify(data, null, '\t') : ''
    )

    // Получаем данные при монтировании компонента
    fetchData(1);
</script>

Важная информация! Асинхронные методы возвращаемые префетч-стором, являются асинхронными, однако на стороне SSR они регистрируются через хук onPrefetch, соответственно их нельзя использовать внутри других хуков (прим. onMounted). И ффактически, на стороне SSR эти методы ничего не вернут. На стороне клиента они работают как обычные асинхронные методы.

Префетч данных внутри компонента через useAsyncData (ОСУЖДАЕМ!)

Библиотека так же предоставляет собственную альтернативу useAsyncData из Nuxt. Но мы настоятельно рекомендуем не использовать его, по причине низкой производительности

<!--App.vue-->
<template>
    <div>
        <span v-if="loading">Загрузка данных...</span>
        <span v-else-if="error">Не удалось загрузить данные</span>
        <pre v-else>{{ serializedData }}</pre>
    </div>
</template>

<script setup lang="ts">
    import { computed, defineProps } from 'vue'
    import { useAsyncData } from "lite-ssr/vue";


    // Инициализируем асинхронный запрос
    const fetchTodo = async (id: number) => {
        const response = await fetch(`https://jsonplaceholder.typicode.com/todos/${id}`);
        if (!response.ok) throw new Error();
        return response.json();
    };

    // Выполняем запрос
    const { data, loading, error } = useAsyncData('data', () => fetchTodo(1));

    // Сериализуем данные для удобочитаемости
    const serializedData = computed( 
        () => data ? JSON.stringify(data, null, '\t') : ''
    )
</script>

Повторимся, мы крайне не рекомендуем использовать этот подход. Т.к. для отслеживания полученных значений функции требуется получать путь компонента, его пропсы и др. информацию для верной передачи этих данных на клиент. Вместо этого лучше используйте Префетч-сторы!

🧑‍💻vue-router, unhead и нестандартное использование

Здесь описаны различные примеры использования фреймворка

Регистрация vue-router

При регистрации роутера, необходимо правильно зарегистрировать history. Пример использования:

// router.ts
import { createMemoryHistory, createRouter, createWebHistory } from 'vue-router'
import routes from './routes';

const baseUrl = import.meta.env.BASE_URL // Берём baseUrl из meta.env
const history = import.meta.env.SSR ? 
    createMemoryHistory(baseUrl) :  // Для SSR регистрируем createMemoryHistory
    createWebHistory(baseUrl) // Для клиента стандартно

const router = createRouter({
  history,
  routes
})

export default router

Регистрация @unhead/vue

Не смотря на то, что библиотека поддерживает unhead, прямой зависимости от него он не имеет, по этому на стороне клиента его нужно зарегистрировать самостоятельно:

// main.ts
import { createApp } from 'lite-ssr/vue'
import App from './app/App.vue'
import { createHead } from '@unhead/vue'

const app = createApp(App)
app.use(createHead()) // Регистрируем @unhead/vue
app.mount('#app');

export default app;

Асинхронная регистрация приложения

Если вам требуется асинхронно получить данные, для регистрации приложения. (Конфигурации плагинов и т.д.), вы можете использовать defineAsyncApp:

// main.ts
import { createApp, defineAsyncApp } from 'lite-ssr/vue'
import App from './app/App.vue'
import { getRouter } from './app/router'

export default defineAsyncApp(async () => {
    const app = createApp(App)
    const router = await getRouter();

    app.use(router);
    app.mount('#app');

    return app;
})

Кастомный index.html

Фреймворк имеет собственный index.html, на основе которого генерируется конечный html файл. В целом подключение библиотек можно сделать через само приложение, либо в секции headв lssr.config.ts.

Если вам всё-таки требуется указать собственную реализацию index.html, необходимо добавить соответствующий путь в конфигурацию плагина lssrVite:

lssrVite({
    head: "./index.html"
})

Стандартный index.html:

<!DOCTYPE html>
<html<!--htmlAttrs-->>
  <head>
    <!--headTags-->
    <!--preload-links-->
    <!--entry-styles-->
  </head>
  <body<!--bodyAttrs-->>
    <!--bodyTagsOpen-->
    <div id="app">
      <!--app-html-->
    </div>
    <!--initial-state-->
    <!--entry-scripts-->
    <!--bodyTags-->
  </body>
</html>

💻 Технологии