Skip to content

README.md

Latest commit

 

History

History
342 lines (250 loc) · 7.92 KB

README.md

File metadata and controls

342 lines (250 loc) · 7.92 KB

VK Mini App Starter

A reusable starter repository for VK Mini Apps with a separated frontend and backend.

Repository: https://github.com/devflex-pro/vk-mini-app-starter-kit

This project is provided as is. It is intended as a reusable starter, reference implementation, and foundation for new VK Mini Apps, not as a finished production product.

What's Included

  • Frontend: React + TypeScript + Vite + VKUI v8 + VK Bridge
  • Backend: NestJS + TypeScript + MongoDB + Mongoose
  • Basic VK Mini App initialization
  • Shared frontend VK layer in shared/vk
  • Shared frontend API client in shared/api
  • Basic entities/user model on both frontend and backend
  • Shared backend auth actor
  • Example user sync flow with the backend
  • Development fallback for running outside the VK container
  • Strict TypeScript checks for frontend and backend
  • GitHub Actions CI for frontend and backend
  • MIT license

Purpose

This repository is a starting point for new VK Mini Apps, not a complete product.

Things that are meant to stay:

  • Project structure
  • Build and environment setup
  • VK Bridge integration
  • Basic backend modules and validation

Things that are usually replaced in a real project:

  • App shell in frontend/src/app/App.tsx
  • Example user sync flow
  • MongoDB schemas and API endpoints for the target domain
  • UI text, screens, and documentation

Structure

vk-mini-app-starter-kit/
  frontend/
  backend/

Frontend

  • React
  • TypeScript
  • Vite
  • VKUI v8
  • VK Bridge
  • Feature-Sliced Design as the target starter architecture

Current frontend structure:

frontend/src/
  app/
  main.tsx
  pages/
  widgets/
  features/
  entities/
  shared/

Layer responsibilities:

  • shared/vk: wrappers around vk-bridge, launch params parsing, bridge init, user info loading, VK environment detection
  • shared/api: shared fetch client with JSON parsing, headers, and normalized errors
  • entities/user: user types and the getUserFullName domain utility
  • features/example-user-sync: orchestration of the demo flow without direct VK logic inside UI components
  • widgets/example-user-sync: demo UI block built on top of the feature
  • pages/home: page composition

Intentionally omitted for simplicity:

  • Global state manager
  • Complex navigation
  • Separate design-system layer on top of VKUI
  • Complex data-access architecture

Backend

  • NestJS
  • MongoDB
  • Mongoose
  • class-validator
  • class-transformer

Current backend structure:

backend/src/
  common/
  entities/
  users/
  vk/

Module responsibilities:

  • common/auth: shared actor contract and current actor decorator
  • common/http: base request type for auth/context data
  • entities/user: Mongoose schema and user response mapping
  • users: demo user sync use case
  • vk: launch params validation, guard, decorator, and debug/context endpoint

What Works Out Of The Box

The starter contains a minimal user flow:

  1. Frontend initializes VKWebAppInit.
  2. Frontend requests the user via VKWebAppGetUserInfo.
  3. In development mode, frontend uses a fallback user when VK Bridge is unavailable.
  4. Frontend sends launch params to the backend via Authorization: Bearer ....
  5. Backend validates sign, checks vk_user_id against the request body, and upserts the user by vkId.
  6. Frontend renders loading, error, and success states.

This flow is meant as a working reference integration. For a real project, it can be simplified, replaced, or removed.

Important details:

  • The demo flow stays isolated from the app shell.
  • Frontend VK logic is not duplicated across components.
  • Backend does not trust vkId from the request body without verified launch params.
  • Development fallback is available outside production.

Quick Start

1. Start MongoDB

With Docker Compose:

docker compose up -d

Or manually:

docker run -d \
  --name vk-miniapp-mongo \
  -p 27017:27017 \
  -e MONGO_INITDB_DATABASE=vk_miniapp_starter \
  mongo:7

2. Start Backend

cd backend
cp .env.example .env
npm install
npm run start:dev

By default, the backend is available at http://localhost:3000, with API routes under /api.

3. Start Frontend

cd frontend
cp .env.example .env
npm install
npm run dev

By default, the frontend is available at http://localhost:5173.

Environment Variables

backend/.env

PORT=3000
MONGODB_URI=mongodb://localhost:27017/vk_miniapp_starter
FRONTEND_URL=http://localhost:5173
VK_APP_SECRET=

frontend/.env

VITE_API_URL=http://localhost:3000/api

If VITE_API_URL is not set, the frontend uses /api.

Example API

The starter currently includes one demo users module.

GET /api/users/health

Checks that the users module is available.

Response:

{
  "ok": true
}

GET /api/vk/context

Checks the backend auth/context layer populated by the vk module from launch params.

This endpoint is mainly useful as a starter debug/inspection endpoint.

Response:

{
  "actor": {
    "appId": 123456,
    "isAuthenticated": true,
    "isDevFallback": false,
    "platform": "mobile_android",
    "userId": 123
  },
  "launchParams": {
    "appId": 123456,
    "isDevFallback": false,
    "isVerified": true,
    "platform": "mobile_android",
    "userId": 123
  }
}

POST /api/users/sync

Example VK user synchronization with the backend.

For requests from a VK Mini App, the frontend passes launch params in the header:

Authorization: Bearer vk_app_id=...&vk_user_id=...&sign=...

In development mode, the backend allows a local fallback when launch params are missing. This fallback is disabled in production.

Important details:

  • The endpoint is a working demo use case.
  • Verified VK context comes from the backend guard, not from the request body.
  • platform and raw VK context are taken from verified launch params when available.
  • The endpoint structure stays simple so it can be replaced easily in a real project.

Request:

{
  "vkId": 123,
  "firstName": "Ivan",
  "lastName": "Petrov",
  "photo200": "https://...",
  "photo100": "https://...",
  "platform": "mobile_android",
  "raw": { "...": "..." }
}

Response:

{
  "id": "mongo_id",
  "vkId": 123,
  "firstName": "Ivan",
  "lastName": "Petrov",
  "photo200": "https://...",
  "photo100": "https://...",
  "platform": "mobile_android",
  "lastSeenAt": "2026-04-10T12:00:00.000Z",
  "createdAt": "2026-04-10T12:00:00.000Z",
  "updatedAt": "2026-04-10T12:00:00.000Z"
}

Validation

Run checks locally:

cd frontend && npm run lint
cd frontend && npm run build
cd backend && npm run lint
cd backend && npm run build

The same checks run in GitHub Actions CI. CI also runs npm audit for both packages.

Current checks:

  • Frontend lint: strict TypeScript check
  • Frontend build: production build with Vite
  • Backend lint: strict TypeScript check
  • Backend build: NestJS build

Security Notes

The current demo flow is not a complete production authentication system.

Before production use, consider adding:

  • Server-side verification of the source of user data
  • Session binding to verified launch params
  • Server-side VK API calls when needed
  • Clear separation between demo user sync and real authorization logic

What is already included:

  • Launch params are verified on the backend.
  • sign is validated before the demo user sync flow uses VK context.
  • Auth actor is extracted into shared backend context.
  • Frontend passes launch params explicitly instead of relying on implicit browser context.

Possible Next Steps

  • Keep the example user flow isolated from the app shell.
  • Replace the starter screen with a navigation shell.
  • Add a top-level backend health check.
  • Add more reusable example modules on top of the current shell.

License

MIT. See LICENSE.

Maintainer

The maintainer is available for work, collaboration, and full-stack product development.

Telegram: @devflexpro
Email: devflex.pro@gmail.com