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