Архітектурні правила Nuxt 4 для frontend-розробника

Nuxt 4 організовує проєкт у три світи: app/ (Vue-фронтенд), server/ (Nitro-бекенд) і shared/ (код для обох). Більшість архітектурних помилок — це код, покладений не в той світ. Ось правила.

Розділяй код за контекстом

Структуруй проєкт так, щоб кожен шар мав одну відповідальність:

• app/ — усе, що стосується Vue: компоненти, сторінки, композабли, лейаути, фронтенд-утиліти.
• server/ — API-маршрути, middleware, серверні утиліти.
• shared/ — код, спільний для app і server.

Що зберігати в shared/

Лише універсальний код, що не залежить від браузера чи Node.js: форматери, валідатори, мапи статусів, чисті хелпери та спільні типи TypeScript. Якщо функція звертається до window, document, cookies чи runtimeConfig — їй не місце в shared/.

• shared/utils — чисті функції (форматування, обчислення, мапери).
• shared/types — інтерфейси й типи, що використовуються між контекстами, напр. форма User для UI та API.

Куди класти фронтенд-код

• app/utils — фронтенд-специфічні утиліти (DOM-хелпери, browser API, форматування, повʼязане з UI).
• app/composables — лише Vue Composition logic (реактивний стан, useX-хуки). Не звалюйте сюди звичайні хелпери.

Куди класти бекенд-код

server/utils — суто серверна логіка: доступ до бази, робота із секретами, виклики сторонніх API. Цей код ніколи не має потрапляти в клієнтський бандл.

Авто-імпорт: знай його межі

Nuxt 4 авто-імпортує з app/composables, app/utils і server/utils. Важливо: shared/ не авто-імпортується — його імпортують явно. Ця явна межа — це фіча: вона не дає спільному коду тихо привʼязуватися до одного контексту.

Ніколи не змішуй frontend і backend

Тримайте нарізно в одному файлі: window, DOM API і localStorage — лише клієнт; клієнти БД, секрети й Node-модулі — лише сервер. shared/ — для того, що безпечне в обох.

Практичне правило

Перед створенням файлу постав три питання: Чи потрібен браузер? Чи потрібен сервер? Чи функція чиста? Відповідь підкаже, де він житиме — у app/, server/ чи shared/. Чітка структура, передбачуваний авто-імпорт, без витоків між клієнтом і сервером — ось Nuxt 4 кодова база, що масштабується.