{"id":13003,"library":"cordova-serve","title":"Cordova Serve","description":"Cordova Serve is an official Apache Cordova project providing local web server capabilities essential for developing and testing Cordova applications. It integrates deeply with `cordova-lib` and `cordova-browser` to serve web assets, facilitating development workflows such as live reloading and opening the application in a browser. The current stable version is 4.0.1, with releases typically occurring as needed to address bugs, introduce new features, or update dependencies within the broader Cordova ecosystem. Its primary differentiator is its tight integration with the Cordova CLI and project structure, offering a streamlined local development experience for hybrid applications.","status":"active","version":"4.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/apache/cordova-serve","tags":["javascript","cordova","server","apache"],"install":[{"cmd":"npm install cordova-serve","lang":"bash","label":"npm"},{"cmd":"yarn add cordova-serve","lang":"bash","label":"yarn"},{"cmd":"pnpm add cordova-serve","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides core Cordova functionality and is the primary consumer of cordova-serve.","package":"cordova-lib","optional":false},{"reason":"Provides browser platform support, often used in conjunction with cordova-serve for testing.","package":"cordova-browser","optional":false}],"imports":[{"note":"The primary function exported for starting the server. CommonJS users should use destructuring.","wrong":"const serve = require('cordova-serve');","symbol":"serve","correct":"import { serve } from 'cordova-serve';"},{"note":"Type definition for the server configuration options, useful in TypeScript projects.","symbol":"ServeOptions","correct":"import { ServeOptions } from 'cordova-serve';"},{"note":"While named `serve` is common, it might also be exported as a default. Check library's specific export style if issues arise.","wrong":"import { serve } from 'cordova-serve';","symbol":"default","correct":"import serve from 'cordova-serve';"}],"quickstart":{"code":"import { serve } from 'cordova-serve';\nimport * as path from 'path';\n\nconst projectRoot = path.resolve(__dirname, 'test_app');\nconst wwwDir = path.join(projectRoot, 'www');\n\nconst options = {\n  port: 8000,\n  root: wwwDir,\n  browser: 'default', // 'none' or 'safari', 'chrome', etc.\n  livereload: true, // Enable live reload functionality\n  consolelog: true, // Enable console log forwarding\n  verbose: true // Enable verbose logging\n};\n\nasync function startServer() {\n  try {\n    console.log(`Starting Cordova server for '${wwwDir}' on port ${options.port}...`);\n    const server = await serve(options);\n    console.log(`Server running at http://localhost:${server.port}`);\n    console.log('Press Ctrl+C to stop the server.');\n    // In a real application, you might want to add a way to stop the server\n    // For this example, it will run until the process is terminated.\n  } catch (error) {\n    console.error('Failed to start Cordova server:', error);\n    process.exit(1);\n  }\n}\n\nstartServer();","lang":"typescript","description":"Demonstrates how to import and start the `cordova-serve` server with common options like port, root directory, and live reload."},"warnings":[{"fix":"Update any custom code interacting with `cordova-serve`'s asynchronous functions to use standard Promise-based syntax (e.g., `async/await` or `.then().catch()`).","message":"Starting with version 2.0.0, the internal API of `cordova-serve` was converted to use native JavaScript Promises, completely removing the dependency on the `q` library. Any custom extensions or direct interactions with the internal asynchronous operations of `cordova-serve` from prior versions will require significant refactoring.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Ensure your development environment uses Node.js version 10 or newer. Consider using a Node Version Manager (NVM) to easily switch between Node.js versions.","message":"As of `cordova-serve` version 4.0.1 (and potentially earlier versions like 2.0.0), the package explicitly requires Node.js version 10 or higher. Running with older Node.js versions will result in errors.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"To prevent a browser from opening automatically, explicitly set the `browser` option to `'none'` when invoking the serve function.","message":"Version 2.0.0 introduced a change where `cordova-serve` will use the default system browser if no specific browser is provided in the configuration. This might open an unexpected browser tab if you previously relied on no browser being opened by default.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Upgrade to `cordova-serve` version 2.0.1 or higher to benefit from the `opn` module and avoid potential issues with the deprecated `open` dependency.","message":"Version 2.0.1 replaced the deprecated `open` module with `opn` for opening URLs in a browser. While this is an internal fix, older versions of `cordova-serve` relying on the `open` module might encounter issues if `open` becomes entirely unmaintained or incompatible with newer Node.js versions.","severity":"gotcha","affected_versions":"<2.0.1"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Run `npm install cordova-serve` in your project directory or `npm install -g cordova-serve` for global usage.","cause":"The `cordova-serve` package is not installed in the current project or globally.","error":"Error: Cannot find module 'cordova-serve'"},{"fix":"Either stop the process currently using the port, or configure `cordova-serve` to use a different port via the `port` option (e.g., `port: 8080`).","cause":"The specified port (e.g., 8000) is already being used by another process on your system.","error":"EADDRINUSE: address already in use :::8000"},{"fix":"Update your Node.js installation to version 10 or higher. Tools like NVM (Node Version Manager) can help manage multiple Node.js versions.","cause":"Your current Node.js version does not meet the minimum requirement of `cordova-serve`.","error":"Error: Node.js version X.Y.Z is not supported. Please use Node.js >= 10.0.0."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"cordova"}