meeko init-framework

meeko init-framework creates the framework starter: file-based routes in app/pages, a layout preserving the shell during navigation, global styles and minimal configuration. You do not need server/runtime.ts or Redis to get started: in development, sessions live in memory. It neither installs dependencies nor overwrites files.

Usage#

npx @meekojs/meeko init-framework tienda

Proyecto creado en C:\proyectos\tienda
Siguiente paso: cd C:\proyectos\tienda && npm install && npm run dev

Type#

meeko init-framework <directorio>

Parameters#

Result#

tienda/
├── .env.example            commented MEEKO_* variables
├── .gitignore              node_modules/, .meeko/, .env
├── README.md
├── meeko.config.ts         defineMeekoConfig({ layers: [], modules: [], imports: { serverDirs: [] } })
├── package.json
├── tsconfig.json           references .meeko/tsconfig.app.json, server and shared
├── public/.gitkeep
└── app/
    ├── app.meeko           the root document
    ├── layouts/default.meeko
    ├── pages/index.meeko   render: "prerender", with a counter
    └── styles/main.css     global styles, loaded automatically

package.json receives these scripts and pins @meekojs/meeko to the exact version of the CLI that created it, with @types/node, typescript and vite as development dependencies:

If the folder had pnpm-lock.yaml, the next step says pnpm install && pnpm run dev.

Examples#

A new application, from start to finish#

npx @meekojs/meeko init-framework tienda
cd tienda
npm install
npm run dev      # http://localhost:4173
npm run check    # types and contracts
npm run build    # .meeko/output/node

npm start in production requires a persistent session store (MEEKO_REDIS_URL or sessions in server/runtime.ts); see meeko start.

Over an existing package.json#

With a folder containing only pnpm-lock.yaml and this package.json:

{ "name": "tienda", "scripts": { "test": "node --test" } }

meeko init-framework .

Proyecto creado en C:\proyectos\tienda
Siguiente paso: pnpm install && pnpm run dev

{
  "name": "tienda",
  "scripts": {
    "test": "node --test",
    "dev": "meeko dev .",
    "check": "meeko check .",
    "build": "meeko build .",
    "start": "meeko start ."
  },
  "private": true,
  "type": "module",
  "engines": { "node": ">=24" },
  "dependencies": { "@meekojs/meeko": "1.6.0" },
  "devDependencies": { "@types/node": "^24.0.0", "typescript": "^7.0.2", "vite": "^8.3.5" }
}

Existing fields, scripts and dependencies are preserved; private, type and engines.node are set. The version number is that of the CLI you ran.

In a monorepo#

pnpm exec meeko init-framework apps/tienda
pnpm install
pnpm -F tienda dev

Scripts use . as the directory, so they work with pnpm -F or from the application folder.

Common mistakes#

A nonempty folder#

meeko init-framework tienda   # tienda already has app/ or a README.md

El destino no está vacío: C:\proyectos\tienda (app, README.md). Since 1.7, as with meeko init, the message lists the blocking entries.

meeko init-framework tienda-nueva

Lockfiles without their package.json#

# tienda has bun.lock or node_modules, but no package.json
meeko init-framework tienda

El destino no está vacío: C:\proyectos\tienda (sin package.json): lockfiles without their package.json belong to another project. A folder containing only .git (git init tienda) is accepted since 1.7; until 1.6 it was rejected.

cd tienda && npm init -y && meeko init-framework .

A package.json already defining dev, check, build or start#

# package.json with "scripts": { "dev": "vite" }
meeko init-framework .

El destino ya define el script dev: C:\proyectos\tienda. Nothing is written.

# rename or remove the script and run again
meeko init-framework .

Notes#

• .meeko/ is not versioned. The starter's .gitignore excludes it, along with .env. Types and entry points are regenerated with meeko dev or meeko check.
• No server to configure. Sessions work without server/runtime.ts: in memory during development and, in production, in Redis through MEEKO_REDIS_URL. Add server/runtime.ts with defineServerRuntime when you need services, your own store or Socket policy.
• .env.example. Documents MEEKO_PORT, MEEKO_HOST, MEEKO_PUBLIC_ORIGIN, MEEKO_REDIS_URL, MEEKO_SESSION_TTL, MEEKO_SESSION_SAMESITE, MEEKO_TRUST_PROXY and, since 1.8, MEEKO_TRUSTED_PROXIES (commented out). Copy it to .env: dev, build, start, preview and check read it.
• Exact version. The project pins the @meekojs/meeko version it was created with; update it manually with your package manager.
• Windows and POSIX. The message uses &&, which works in PowerShell 7, cmd and POSIX.

Related#

• meeko initCreates a standalone SSR project without the framework, with a .meeko component, its Node server and Vite.
• meeko devDevelopment server for a full-stack application, preparing .meeko/ types and serving the application with Vite, SSR and HMR.
• meeko checkChecks an entire project, or a single .meeko component, with Meeko and TypeScript diagnostics, and generates .meeko/ types.
• defineMeekoConfigDeclares typed meeko.config.ts configuration (layers, modules, auto-imports, aliases, server, CSS, document, sitemap and theme) without changing it.
• Create an applicationMeeko as a full-stack framework
• ConfigurationMeeko as a full-stack framework