LITE-SSR

Легковесная реализация SSR для Vite.

---

💾 О проекте

Данная библиотека разработана для организации 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>

---

💻 Технологии

---