@marko/run
Advanced tools
And when you build your production-ready app:
Warning This project is in BETA - use at your own peril, but please do provide helpful feedback.
npm install @marko/run
marko-run makes it easy to get started without little to no config. The package ships with a default Vite config and node-based adapter.
To get started from a template:
npm init marko -- -t basiccd ./<PROJECT_NAME>npm run devOr manually create a project:
@marko/runsrc/routes/+page.markonpm exec marko-runFinally open http://localhost:3000 🚀
dev - Start a development server in watch mode
> npm exec marko-run
or (with explicit sub command)
> npm exec marko-run dev
build - Create a production build
> npm exec marko-run build
preview - Create a production build and start the preview server
> npm exec marko-run preview
The plugin looks for route files in the configured routes directory. By default, that’s ./src/routes, relative to the Vite config file.
To change what directory routes are found in:
// vite.config.ts
import { defineConfig } from "vite";
import marko from "@marko/run/vite";
export default defineConfig({
plugins: [
marko({
routesDir: "src/pages", // Use `./src/pages` (relative to this file) as the routes directory
}),
],
});
The router only recognizes certain filenames which are all prefixed with + (Why?). The following filenames will be discovered in any directory inside your application’s routes directory.
+page.markoThese files establish a route at the current directory path which will be served for GET requests with the HTML content of the page. Only one page may exist for any served path.
+layout.markoThese files provide a layout component, which will wrap all nested layouts and pages.
Layouts are like any other Marko component, with no extra constraints. Each layout receives the request, path params, URL, and route metadata as input, as well as a renderBody which refers to the nested page that is being rendered.
<main>
<h1>My Products</h1>
<${input.renderBody}/> // render the page or layout here
</main>
+handler.*These files establish a route at the current directory path which can handle requests for GET, POST, PUT, and DELETE HTTP methods.
Typically, these will be .js or .ts files depending on your project. Like pages, only one handler may exist for any served path. A handler should export functions
GET, POST, PUT, or DELETE.Receives a context and next argument,
context argument contains the WHATWG request object, path parameters, URL, and route metadata.next argument will call the page for GET requests where applicable or return a 204 response.Return a WHATWG response, throw a WHATWG response, and return undefined. If the function returns undefined the next argument with be automatically called and used as the response.
export function POST(context, next) {
const { request, params, url, meta } = context;
return new Response('Successfully updated', { status: 200 });
}
export function PUT(context, next) {
// `next` will be called for you by the runtime
}
export async function GET(context, next) {
// do something before calling `next`
const response = await next();
// do something with the response from `next`
return response;
}
export function DELETE(context, next) {
return new Response('Successfully removed', { status: 204 });
}
+middleware.*These files are like layouts, but for handlers. Middleware files are called before handlers and let you perform arbitrary work before and after.
Note: Unlike handlers, middleware run for all HTTP methods.
default export that can be one of the following
Receives a context and next argument,
context argument contains the WHATWG request object, path parameters, URL, and route metadata.next argument will call the page for GET requests where applicable or return a 204 response.Return a WHATWG response, throw a WHATWG response, and return undefined. If the function returns undefined the next argument with be automatically called and used as the response.
export default async function(context, next) {
const requestName = `${context.request.method} ${context.url.href}`;
let success = true;
console.log(`${requestName} request started`)
try {
return await next(); // Wait for subsequent middleware, handler, and page
} catch (err) {
success = false;
throw err;
} finally {
console.log(`${requestName} completed ${success ? 'successfully' : 'with errors'}`);
}
}
+meta.*These files represent static metadata to attach to the route. This metadata will be automatically provided on the route context when invoking a route.
In addition to the files above which can be defined in any directory under the routes directory, some special files can only be defined at its top level.
These special pages are subject to a root layout file (pages/+layout.marko in the default configuration).
+404.markoThis special page responds to any request where:
Accept request header includes text/htmlResponses with this page will have a 404 status code.
+500.markoThis special page responds to any request where:
Accept request header includes text/htmlResponses with this page will have a 500 status code.
Given the following routes directory structure
routes/
about/
+handler.js
+layout.marko
+middleware.js
+page.marko
+layout.marko
+middleware.js
+page.marko
When the path /about is requested, the routable files execute in the following order:
sequenceDiagram
participant MW1 as routes/+middleware.js
participant MW2 as routes/about/+middleware.js
participant H as routes/about/+handler.js
participant L1 as routes/+layout.marko
participant L2 as routes/about/+layout.marko
participant P as routes/about/+page.marko
Note over L1,P: Combined at build-time as a single component
MW1->>MW2: next()
MW2->>H: next()
H->>L1: next()
L1->L2: ${input.renderBody}
L2->P: ${input.renderBody}
L1-->>H: Stream Response
H-->>MW2: Response
MW2-->>MW1: Response
Within the routes directory, the directory structure determines the path from which the route is served. There are four types of directory names: static, pathless, dynamic, and catch-all.
Static directories - The most common type, and the default behavior. Each static directory contributes its name as a segment in the route's served path, like a traditional fileserver. Unless a directory name matches the requirements for one of the below types, it is seen as a static directory.
Examples:
/foo
/users
/projects
Pathless directories - These directories do not contribute their name to the route's served path. Directory names that start with an underscore (_) will be ignored when parsing the route.
Examples:
/_users
/_public
Dynamic directories - These directories introduce a dynamic parameter to the route's served path and will match any value at that segment. Any directory name that starts with a single dollar sign ($) will be a dynamic directory, and the remaining directory name will be the parameter at runtime. If the directory name is exactly $, the parameter will not be captured but it will be matched.
Examples:
/$id
/$name
/$
Catch-all directories - These directories are similar to dynamic directories and introduce a dynamic parameter, but instead of matching a single path segment, they match to the end of the path. Any directory that starts with two dollar signs ($$) will be a catch-all directory, and the remaining directory name will be the parameter at runtime. In the case of a directory named $$, the parameter name will not be captured but it will match. Catch-all directories can be used to make 404 Not Found routes at any level, including the root.
Because catch-all directories match any path segment and consume the rest of the path, you cannot nest route files in them and no further directories will be traversed.
Examples:
/$$all
/$$rest
/$$
Flat routes let you define paths without needing additional folders. Instead the folder structure can be defined either in the file or folder name. This allows you to decouple your routes from your folder structure or co-locate them as needed. To define a flat route, use periods (.) to deliniate each path segment. This behaves exacly like creating a new folder and each segment will be parsed using the rules described above for static, dynamic and pathless routes.
Flat routes syntax can be used for both directories and routable files (eg. pages, handlers, middleware, etc.). For these files, anything preceeding the plus (+) will be treated as the flat route.
For example to define a page at /projects/$projectId/members with a root layout and a project layout:
Without flat routes you would have a file structure like:
routes/
projects/
$projectId/
members/
+page.marko
+layout.marko
+layout.marko
With flat routes move the path defined by the folders into the files and separate with a period
routes/
+layout.marko
projects+layout.marko
projects.$projectId.members+page.marko
Additionally, you can continue to organize files under folders to decrease duplication and use flat route syntax in the folder name
routes/
projects.$projectId/
+layout.marko
members+page.marko
+layout.marko
Finally, flat routes and routes defined with directories are all treated equally and merged together. For example this page will have layout
routes/
projects/
$projectId/
+layout.marko
projects.$projectId+page.marko
Along with descibing multiple segements, flat route syntax supports defining routes that match more than one path and segments that are optional. To describe a route that matches multiple paths, use a comma (,) and define each route.
For example the following page matches /projects/$projectId/members and /projects/$projectId/people
routes/
projects.$projectId.members,projects.$projectId.people+page.marko
This file name is a bit long so you might do something like this
routes/
projects.$projectId
members,people+page.marko
We can simplify this by introducing another concept: grouping. Groups allows you to define segments within a flat route that match multiple sub-paths by surrounding them with parentheses (( and )). For the example, this means you can do the following:
routes/
projects.$projectId.(members,people)+page.marko
This is a simple example of grouping but you can nest groups and make them as complicated as you want.
The last concept is optionallity. By introducing an empty segment or pathless segment along with another value you can make that segment optional. For example, If we want a page that matches /projects and /projects/home, you can create a flat route that optionally matches home
routes/
projects.(home,)+page.marko
or
routes/
projects.(home,_pathless)+page.marko
While both of these create a route which matches the paths, they have slightly different semantics. Using a pathless segment is the same as creating a pathless folder which allows you to isolate middleware and loayouts. Using an empty segement is the same as defining a file at the current location.
To include a control character (.,+()$_) as a literal in a route path, it can be surrounded with graves (`). For example to create a route to /sitemap.xml
routes/
`sitemap.xml`/
+handler.ts
or
routes/
sitemap`.`xml
+handler.ts
or
routes/
sitemap`.`xml+handler.ts
This package’s Vite plugin discovers your route files, generates the routing code, and registers the @marko/vite plugin to compile your .marko files.
// vite.config.ts
import { defineConfig } from "vite";
import marko from "@marko/run/vite"; // Import the Vite plugin
export default defineConfig({
plugins: [marko()], // Register the Vite plugin
});
Adapters provide the means to change the development, build, and preview process to fit different deployment platforms and runtimes while allowing authors to write idiomatic code.
Specify your adapter in the Vite config when registering the @marko/run plugin
// vite.config.ts
import { defineConfig } from "vite";
import marko from "@marko/run/vite";
import netlify from "@marko/run-adapter-netlify"; // Import the adapter
export default defineConfig({
plugins: [
marko({
adapter: netlify({ edge: true }), // Configure and apply the adapter
}),
],
});
Generally, when using an adapter, this runtime will be abstracted away.
import * as Run from '@marko/run/router`;
Context is passed to middleware and handler functions as the first paramter and is available in Marko templates as $global. The context object contains information about the current request with the following properties
route - A string identifying the current route
request - Current WHATWG Request instance
method - HTTP method of the current request
params - Record<string, string> of the route parameters
meta - Meta data loaded from the current route's +meta file
platform - Additional data provided by the adapter
parent - When context.fetch is called the current context will become the parent of the new context created for the fetch request, otherwise this field will be undefined.
fetch
fetch(resource: string | URL | Request, init?: RequestInit): Promise<Response>;
Creates a response by making a new request to the router. This method has the same signature as native fetch.
renderrender<T>(template: Marko.Template<T>, input: T, init?: ResponseInit): Response;
Creates a response that streams the given Marko template and sets the Content-Type header to text/html.
redirectredirect(to: string | URL, status?: number): Response;
Creates a redirect response that will resolve relative paths.
backback(fallback?: string | URL, status?: number): Response;
Creates a redirect response that uses the current request referer or an optional fallback.
Run.fetchasync function fetch<T>(request: Request, platform: T) => Promise<Response | void>;
This asynchronous function takes a WHATWG Request object and an object containing any platform-specific data you may want access to, and returns any of
Response object (generated from executing any matched route files)undefined (if the request was not explicitly handled)404 status code response (if no route matches the requested path)500 status code response (if an error occurs)Express example:
import express from "express";
import * as Run from "@marko/run/router";
express()
.use(async (req, res, next) => {
const request = ...; // code to create a WHATWG Request from `req`
const response = await Run.fetch(request, {
req,
res
});
if (response) {
// ...code to apply a response to `res`
} else {
next();
}
})
.listen(3000);
In some cases, you might want more control over when route matching and invocation (creating a response) occur. For instance, you may have middleware in your server which needs to know if there is a matched route. The runtime provides these additional methods:
Run.matchinterface Route {
params: Record<string, string>;
meta: unknown;
}
function match(method: string, pathname: string) => Route | null;
This synchronous function takes an HTTP method and path name and returns an object representing the best match, or null if no match is found.
params - a { key: value } collection of any path parameters for the routemeta - metadata for the routeRun.invokeasync function invoke(route: Route, request: Request, platform: any) => Promise<Response | void>;
This asynchronous function takes a route object returned by Run.match the request and platform data and returns a response in the same way the Run.fetch does.
Express example:
import express from "express";
import * as Run from "@marko/run/router";
express()
.use((req, res) => {
const matchedRoute = Run.match(req.method, req.path);
if (matchedRoute) {
req.match = matchedRoute;
}
})
// ...other middleware
.use(async (req, res, next) => {
// Check if a route was previously matched
if (!req.match) {
next();
return;
}
const request = ...; // code to create a WHATWG Request from `req`
const response = await Run.invoke(req.match, request, {
req,
res
});
if (response) {
// ...code to apply a response to `res`
} else {
next();
}
})
.listen(3000);
marko/run provides a global namespace MarkoRun with the following types:
MarkoRun.Handler - Type that represents a handler function to be exported by a +handler or +middleware file
MarkoRun.Route - Type of the route's params and metadata
MarkoRun.Context - Type of the request context object in a handler and $global in your Marko files. This type can be extended using TypeScript's module and interface merging by declaring a Context interface on the @marko/run module within your applcation code
declare module "@marko/run" {
interface Context {
customPropery: MyCustomThing; // will be globally defined on MarkoRun.Context
}
}
MarkoRun.Platform - Type of the platform object provided by the adapter in use. This interface can be extended in that same way as Context (see above) by declaring a Platform interface:
declare module "@marko/run" {
interface Platform {
customPropery: MyCustomThing; // will be globally defined on MarkoRun.Platform
}
}
If a TSConfig file is discovered in the project root, the Vite plugin will automatically generate a .d.ts file which provides more specific types for each of your middleware, handlers, layouts, and pages. This file will be generated at .marko-run/routes.d.ts whenever the project is built - including dev.
Note TypeScript will not include this file by default. You should use the Marko VSCode plugin and add it in your tsconfig.
These types are replaced with more specific versions per routable file:
MarkoRun.Handler
MarkoRun.Route
MarkoRun.Context
Once stable @marko/run will replace @marko/serve and improves upon that project in several critical ways.
+page.marko) improve the developer ergonomics quite substantially. While they may cause a double take initially, making these explicit allows colocating additional components, tests, stories, config, utilities, and whatever else you need alongside the page components. With @marko/serve it was far too easy to "accidentally" serve some of your test fixtures :see-no-evil:.@marko/serve left some to be desired which made it difficult to integrate into existing development servers and projects. Because of this, public-facing applications at eBay (the largest consumer of Marko) were not able to bring in @marko/serve. With @marko/run we've worked from the ground up to ensure a flexible enough programmatic API to allow embedding in existing complex applications. Because of this, we're confident that @marko/run will see much more use than @marko/serve and more investment from us!+layout.marko "route file". If you've used Marko before you know it's very easy to treat layouts as normal components. But by bringing these layouts into the router we're able to reduce the amount of JavaScript naively sent to the browser, reduce the amount of boilerplate, and prime ourselves for some plans we have for after Marko 6 is out :eyes:.There's more of course, but we're committed to making @marko/run the best way to build a Marko application.
FAQs
The Marko application framework.
The npm package @marko/run receives a total of 583 weekly downloads. As such, @marko/run popularity was classified as not popular.
We found that @marko/run demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 7 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
Newer packages in this compromise use native extensions and .pth loaders to execute JavaScript stealers in developer environments.
Research
Socket found 37 malicious PyPI wheels that abuse Python startup hooks to launch a Bun-powered credential stealer tied to Mini Shai-Hulud/Miasma.
Security News
RubyGems and Bundler 4.0.13 introduced an opt-in cooldown feature that delays newly published gems during dependency resolution.