meeko dev

meeko dev starts the application in the specified directory (current directory by default) in development mode. It first reads the project's .env, loads meeko.config.ts and its modules and generates Vite entry points, route, contract and auto-import types and, since 1.7, .meeko/types/services.d.ts in .meeko/. It then creates a Node HTTP server with Vite in middleware mode: SSR with uncompiled app/ and server/ modules, component and CSS HMR, and server logs in the browser console.

It does not check types: that is meeko check. It does not serve the production build either: that is meeko start.

Usage#

# at the project root, which contains meeko.config.ts
meeko dev

http://localhost:4173

The meeko init-framework starter declares it as "dev": "meeko dev .", so you usually run npm run dev or pnpm dev.

Type#

meeko dev [directorio]

Options#

Accepts no flags: meeko dev --port 3000 exits with Opción desconocida para dev: --port. Set ports and address through environment variables, in the shell or .env.

Result#

• Standard output, the URL to open, such as http://localhost:4173: since 1.7.1, a loopback (127.0.0.1, ::1) or all-interface address (0.0.0.0, ::) is displayed as localhost, though the server still listens on the configured address. With 0.0.0.0 or ::, adds a Red: http://<IP>:4173 line per network address; with a specific host, displays that host. The first line is always the local URL alone. If no port was specified and 4173 is occupied, it first warns: [meeko] El puerto 4173 está en uso; meeko dev usa el 4174.
• Standard error, without an editor bridge, since 1.7.1, a line after the URL with the reason: Valores en vivo del editor desactivados (MEEKO_EDITOR_BRIDGE=0) or, if listening on a specific non-loopback address, Valores en vivo del editor desactivados (meeko dev escucha en 192.168.1.5, fuera de loopback).
• In .meeko/, generated/ entry points, manifests, types/ declarations and the editor's tsconfig.*.json, like meeko check but without running TypeScript. Generated at startup: types are not regenerated while the process remains alive (run meeko check).
• In .meeko/dev/, the editor bridge descriptor editor-bridge-<puerto>.json, deleted on Ctrl+C, and server.json, the serving process record (pid and startedAt), also deleted on exit. Without the bridge, since 1.7.1, that record adds editorBridge: false and editorBridgeReason so the editor can explain it.
• The process runs until SIGINT or SIGTERM, closing the bridge, Socket, HTTP, application and Vite in that order. A startup error exits with code 1 and the message on standard error.

While running, creating or deleting a page, layout, middleware or server/api, server/rpc or server/socket module rediscovers routes and recreates the application without restarting the process. Changing meeko.config.ts, a module's setup or an existing Socket channel requires restarting.

Examples#

Another port, using the project's .env#

# .env
MEEKO_PORT=3000

meeko dev
# http://localhost:3000

A shell variable overrides .env: MEEKO_PORT=3100 meeko dev uses 3100 even if .env says otherwise.

Two applications at once#

Without a specified port, the second meeko dev takes the next available one instead of failing, and its HMR uses another derived port:

# terminal 1, in ./tienda
meeko dev
# http://localhost:4173

# terminal 2, in ./panel
meeko dev
# [meeko] El puerto 4173 está en uso; meeko dev usa el 4174
# http://localhost:4174

Test from a phone on the local network#

MEEKO_HOST=0.0.0.0 meeko dev
# http://localhost:4173
# Red: http://192.168.1.20:4173

In PowerShell:

$env:MEEKO_HOST = "0.0.0.0"; meeko dev

The phone opens the URL in the Red: line. The HMR WebSocket and server logs still listen only on 127.0.0.1: the phone's browser receives neither HMR nor logs in its console.

Behind an HTTPS tunnel or proxy#

MEEKO_PUBLIC_ORIGIN=https://mi-tunel.example.com meeko dev

Without it, mutations (API and RPC POST) and sockets arriving with Origin: https://mi-tunel.example.com are rejected because they do not match the local origin.

Another monorepo project#

meeko dev apps/meeko

The path is the project root, not a file: .env, meeko.config.ts, app/ and .meeko/ are read and written inside apps/meeko.

Common mistakes#

Pass the port as a flag#

meeko dev --port 3000

The CLI responds with Opción desconocida para dev: --port, prints usage and exits with code 1. meeko dev has no flags; since 1.7, meeko dev --help prints help.

MEEKO_PORT=3000 meeko dev

A specified port already in use#

With MEEKO_PORT, PORT or server.port, meeko dev does not look for another port: whoever sets it expects that URL.

# another meeko dev (or another program) already listens on 4391
MEEKO_PORT=4391 meeko dev

El puerto 4391 de 127.0.0.1 ya está en uso; usa MEEKO_PORT=<otro puerto> o cierra el otro meeko dev

The process exits with code 1. If you specify no port and all 20 from 4173 are occupied, the message is Los puertos 4173–4192 de 127.0.0.1 ya están en uso; usa MEEKO_PORT=<puerto> o cierra otro meeko dev.

MEEKO_PORT=4392 meeko dev
# or, without an explicit port, let it choose the first available one
meeko dev

Run outside the project root#

cd apps/meeko/app
meeko dev

meeko dev looks for app/pages inside the given directory and fails with ENOENT: no such file or directory, scandir '…\apps\meeko\app\app\pages'. It would also read the wrong .env.

meeko dev apps/meeko

MEEKO_LINK_WATCH=0 and a changing linked Meeko#

With @meekojs/meeko linked to its repository, meeko dev supervises itself and restarts the server when the package's dist/ changes ([meeko] Meeko enlazado cambió; reiniciando meeko dev…). With MEEKO_LINK_WATCH=0, it does not:

MEEKO_LINK_WATCH=0 meeko dev
# then, pnpm -F @meekojs/meeko run build in the other repository

[meeko] Meeko enlazado cambió (…\packages\meeko\dist), pero este meeko dev no se reinicia solo (MEEKO_LINK_WATCH=0): el servidor sigue con el código anterior y el navegador recibe el nuevo. Reinicia meeko dev.

SSR continues with the old runtime and the browser hydrates with the new one: resulting hydration errors are not application errors.

meeko dev

Use MEEKO_LINK_WATCH=0 only if the process must not restart (for example, with a debugger attached), and restart it manually after each package build.

Expect meeko dev to check types#

# CI
meeko dev & sleep 10 && curl -f http://127.0.0.1:4173/

meeko dev serves a page even if another has a type error: Vite strips types without checking them. A TypeScript error only appears in meeko check, meeko build and the editor.

meeko check

Notes#

• Development only. Serves unbundled source modules, with CSP disabled (Vite injects scripts without a nonce) and server logs in the browser. Do not publish it on the Internet; use meeko build and meeko start in production.
• .env. dev, build, start, preview and check read <directorio>/.env first, including MEEKO_PORT or MEEKO_LINK_WATCH. An existing environment variable is never replaced. Changing .env while running restarts Vite and recreates the application; in-memory sessions are lost.
• Ports. Without a specified port, tries 4173 through 4192 and takes the first whose derived HMR port is also available. HMR uses a port derived from HTTP so two projects do not share Vite's 24678.
• Two processes in the same project. Each startup rewrites .meeko/generated/; a second meeko dev in the same directory makes the first reload its SSR entry points. Since 1.7, each meeko dev records its PID in .meeko/dev/server.json and the second warns at startup: [meeko] Otro meeko dev (PID …) ya sirve este proyecto: …. It only warns and continues; use one process per project.
• Windows and POSIX. On Windows, Ctrl+C closes the server and deletes .meeko/dev/editor-bridge-<puerto>.json; killing the process from Task Manager (or with taskkill /F) skips shutdown and leaves the descriptor in .meeko/dev/ (meeko clean removes it). On POSIX, kill (SIGTERM) shuts down gracefully.
• Performance. Startup discovers routes, contracts and auto-imports and writes types before listening, but does not run TypeScript, the slow part of meeko check. Editing an existing page, layout or handler restarts nothing: Vite reloads that module on request.
• Process errors. An unhandled rejection in application code is logged and the server continues; an uncaught exception closes the server with code 1.

Related#

• meeko checkChecks an entire project, or a single .meeko component, with Meeko and TypeScript diagnostics, and generates .meeko/ types.
• meeko buildChecks the project and writes production output to .meeko/output/<adaptador>/, including the client, server and prerendered pages.
• meeko cleanDeletes Meeko-generated files in a project (.meeko/ and the Vite cache) and, with --all, node_modules too, without ever following links.
• devOptions for meeko dev, such as forwarding server code output to the browser console while handling a request.
• meeko (Vite)Meeko's Vite plugin, compiling .meeko imports for the client and SSR, adding HMR and CSS in development, applying auto-imports and generating framework virtual modules.
• ConfigurationMeeko as a full-stack framework
• Server logs in the browser consoleMeeko as a full-stack framework
• Editor bridgeMeeko DevTools