gulp-lonrav — Static Site Build System

Modern Gulp 5-based build system for static websites: landing pages, multipage sites and CMS templates.
Focused on performance, flexibility and developer experience.

---

Suitable for

• Landing pages and marketing sites
• Multipage corporate websites
• Static sites served from a CDN or plain hosting
• CMS templates (manual integration)

Not suitable for

• Single-page or server-rendered applications (React / Vue / Next.js / Nuxt)
• Projects that would benefit from Vite or framework-oriented toolchains

---

Requirements

Node.js >= 20 is required.
npm, pnpm, and yarn are all supported.

---

Quick Start

1. Install dependencies

npm install
# or
pnpm install
# or
yarn install

2. Development

npm run dev

Starts a BrowserSync dev server at http://localhost:3000, compiles templates, styles and scripts on the fly, and watches for changes.

3. Production build

npm run build

Outputs an optimized site to public/.

4. Preview

npm run preview

Builds to public/ and serves it locally.

---

Available Commands

Command	Description
npm run dev	Dev server with watch and live reload
npm run build	Full production build
npm run build:fast	Faster build using the basic profile (skips heavy steps)
npm run preview	Production build + local server
npm run clean	Delete dist/ and public/
npm run lint	ESLint + Stylelint
npm run format	Prettier
npm run check	lint + build
npm run lint:report	Write JSON reports to reports/
npm run ci:quality	lint:report + validate

---

Project Structure

gulp-lonrav/
├── src/              # Source files
│   ├── pages/        # Entry templates → compiled to individual HTML files
│   ├── styles/       # Sass / SCSS / PostCSS / Tailwind sources
│   ├── scripts/      # JavaScript modules (bundled by esbuild)
│   ├── assets/       # Images, fonts, icons, favicons
│   ├── shared/       # Partials, layouts, includes
│   └── static/       # Copied as-is to output root
├── dist/             # Dev build output (generated)
├── public/           # Production build output (generated)
├── gulp/             # Gulp task implementation
├── config/           # Build configuration
├── gulpfile.js       # Task entry point
├── user.config.js    # Local overrides (not committed)
└── package.json

Minimum required structure inside src/:

src/
  pages/
    index.html        ← required
  styles/
    main.scss         ← required
  scripts/
    main.js           ← required
  assets/
    favicons/
      favicon.svg     ← required when favicons feature is enabled

---

Configuration

All build behaviour is controlled by files in config/. They are plain ES modules.

File	Purpose
config/features.js	Enable / disable optional modules
config/paths.js	Source and output paths
config/site.js	siteUrl, basePath, linksMode
config/styles.js	Styles engine, PostCSS options
config/scripts.js	JS target, format, code splitting
config/templates.js	Template engine, minification
config/images.js	Formats, quality, WebP/AVIF
config/svg.js	SVG optimisation and sprite
config/favicons.js	Favicon generation
config/seo.js	Sitemap and robots.txt
config/versioning.js	Asset rev-hashing
config/i18n.js	Localisation

Project-level overrides

Create config.js in the project root to override any value without modifying the base files.
It is deep-merged at runtime:

// config.js
export const site = {
  siteUrl: 'https://example.com',
  basePath: '/my-site',
};

export const styles = {
  engine: 'tailwind',
};

---

Environment Variables

Copy .env.example to .env:

SITE_URL=https://example.com
SITE_BASE_PATH=/my-site
SITE_NAME=My Project
SITE_SHORT_NAME=Project

Read automatically by config/site.js.

---

Template Engines

Plain HTML with @include (file-include) is enabled by default.
Additional engines are supported but not installed:

npm i -D pug
npm i -D ejs
npm i -D nunjucks
npm i -D handlebars

Set the engine in config.js:

export const templates = {
  engine: 'pug', // 'html' | 'pug' | 'ejs' | 'nunjucks' | 'handlebars'
};

---

Styles

SCSS + PostCSS by default (autoprefixer + cssnano in production).

// config.js
export const styles = {
  engine: 'scss', // 'scss' | 'css' | 'tailwind'
};

Tailwind CSS

npm i -D tailwindcss

Create tailwind.config.js, then set engine: 'tailwind' in config.js.

---

JavaScript

Bundled by esbuild. TypeScript is supported out of the box.

// config.js
export const scripts = {
  target: 'es2018',
  format: 'esm',    // 'esm' | 'cjs' | 'iife'
  splitting: false,  // enable for dynamic import chunks
};

---

Feature Flags

Managed in config/features.js. Disabling a module is a fully supported workflow.

Strict policy: if a feature is disabled but its input files exist — dev warns; build fails.

Key flags and their defaults:

Feature	Default	Description
favicons.enabled	true	Generate favicons from favicon.svg
svgSprite.enabled	true	Build SVG sprite from src/assets/icons/
static.enabled	true	Copy src/static/** to output root
media.audio.enabled	false	Audio transcoding
media.video.enabled	false	Video transcoding
versioning.enabled	true	Rev-hash assets
i18n.enabled	false	Multilanguage build
seo.sitemap	true	Generate sitemap.xml
seo.robots	true	Generate robots.txt

---

Build Profiles

Profile	Description
full	All optimizations (default)
basic	Skips favicons, sprite, static, media, versioning, size report
no-favicons	Disables only favicons
no-sprite	Disables only SVG sprite

GULP_LONRAV_PROFILE=basic npm run build
# or
npm run build -- --profile basic

npm run build:fast uses basic automatically.

---

Multilanguage (i18n)

1. Create src/data/locales/en.json, ru.json etc. with flat key-value objects.

2. Enable in config.js:

   export const features = {
     i18n: { enabled: true, defaultLocale: 'en', locales: ['en', 'ru'] },
   };

3. Use $t('key') in templates. A separate output folder is generated per locale.

---

Quality Tools

Linting runs automatically at npm run dev startup and before npm run build. Skipped during npm run preview.

• ESLint — eslint.config.js
• Stylelint — stylelint.config.js
• Prettier — prettier.config.js (not a CI gate; run npm run format locally)
• validateStructure — checks required entry points exist (dev: warn / build: fail)
• validateAssets — checks HTML asset references resolve (dev: warn / build: fail)

---

Documentation Page

Run npm run dev and open http://localhost:3000/docs.html for an interactive reference with structure details, feature guides, FAQ and template syntax examples.

See README_RU.md for the Russian version.

---

License

MIT