When you `serve` a directory, every `.marko` file in that directory becomes a page. A browser is automatically launched and live-reloads as you make changes. It's the simplicity of a static file server plus the power of [the Marko UI language](https://markojs.com/).
## Features
- 🚀 Fastest way to build a Marko app
- 💖 No need to configure webpack, babel, etc.
- ⚡️ Pages live-reload as you make changes
- 📁 Directory-based routes
- 💯 Supports route parameters (`/blog/:id`)
- 🛠 Serve a single component to work on it in isolation
And when you [`build`](../build/README.md) your production-ready app:
- 🔥 Blazing fast server-side rendering
- 📦 Optimized bundles with automatic code splitting
- ✨ Modern JS & CSS for modern browsers, legacy JS & CSS for legacy browsers
## Getting Started
### Hello World
Start by creating and entering a new directory, then serve it [using `npx`](https://docs.npmjs.com/cli/commands/npx) (requires npm 5.2.0+):
```sh
mkdir my-new-app
cd my-new-app/
npx @marko/serve .
```
By running `npx @marko/serve`, a browser tab automatically opens for the current working directory. Since our new directory is empty, you should see an empty directory index:
Let's make a web page! Create a `hello.marko` file within `my-new-app/` with the following:
```marko
Hello World
```
Once you save this file, the directory index will reload and show `hello.marko` as a file:
Follow the `hello.marko` hyperlink to view your new page:
### A custom index
Navigate back to the directory index. Let's create an `index.marko` file with the following:
```marko
Home
```
Once you save this file, the directory index will reload and show our custom index instead:
### Adding a component
Let's add a menu so we can navigate between our pages. Since it’ll be on every page, we'll create it as a component instead of duplicating code for each page.
1. Create a `components/` directory, then add a `main-menu.marko` file inside with the following:
```marko
```
2. Then, add the `` component to both pages:
```marko
Home
```
```marko
Hello World
```
3. We can now use the menu to navigate between pages!
### Route params
What if we want our app to say "Hello" to more than the world? Do we need a new `.marko` file for each thing we want to say hello to?
_Nope._ This is where route parameters come in. **Route parameters** let you use dynamic values from the URL in your templates. Like normal pages, these are powered by your directory structure, but add a special syntax: filenames that contain keywords in square brackets (like `[example]`) create a parameter with the same name as the text between the brackets.
1. Rename `hello.marko` to `hello/[name].marko`, and update its contents to:
```marko
Hello ${input.params.name}
```
2. Try [visiting `http://localhost:3000/hello/params`](http://localhost:3000/hello/params) in your browser.
3. The possibilities are endless! Try adding a few to your menu:
```marko
```
### Go forth and build
When you're ready to let the world see what you've built, run [the `build` command](../build/README.md) to get a production-ready app:
```sh
npx @marko/build .
```
This produces a `build/` directory that contains the app and its assets, all optimized and compressed.
We no longer need `@marko/serve`, `@marko/build`, or any other dependencies. We can run the server using only `node`:
```sh
node build/index.js
```
[Open your browser to `http://localhost:3000/`](http://localhost:3000/) and you'll see the same app, only faster.
This `build/` directory can now be deployed to your favorite hosting service. We're excited to see what you make! ✨
## CLI
### Installation
```sh
npm install --save-dev @marko/serve
```
### Examples
```sh
marko-serve . # serve the current directory
marko-serve ./pages # serve a “pages” directory
marko-serve ./components/example.marko # serve a single component
marko-serve . --inspect-brk # debug by passing a node argument through
```
### Options
- `--port -p`: The port to serve on (default `3000`)
- `--no-browser`: Don't automatically open the browser
- `--verbose`: Show the entire raw build output
- [Any `node` CLI arguments](https://nodejs.org/api/cli.html) are passed to the Node.js server process
## API
> **Warning**:
> Don't import the `@marko/serve` package directly yet. A programmatic API is coming soon.
---
_Source: https://npm.io/package/@marko/serve · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
