On this page
Come into the simplistic, powerful developer cloud. Save money, increase efficiency, and optimize spend with solutions that take away the process and cut the long story short.
Ride more on open source with our commitment to open source. WebQit Cloud lets you build on open technologies that you can always bank on.
Ready for a stress-free go-live experience? Watch this space for when we come in beta.
Web-native is an approach to web tooling that seeks to solve for the traditonal, native web over vendor-specific interests. This is an especially important goal for a web community that is now fragmented into framework silos.
WebQit Community is an initiative to support an obvious community-wide paradigm shift for web-native development. We seek to drive community participation in new ideas for the web platform, and in all the projects that are revisiting much of the assumptions that brought us here, to explore new possibilities around just conventional web languages and APIs.
We're beginning this initiative by giving mentions to the actionable discussions from around the web that are painting this future of the web. It'll be nice to see the whole picture from one place.
Come into the simplistic, powerful developer cloud. Save money, increase efficiency, and optimize spend with solutions that take away the process and cut the long story short.
Ride more on open source with our commitment to open source. WebQit Cloud lets you build on open technologies that you can always bank on.
Ready for a stress-free go-live experience? Watch this space for when we come in beta.
Web-native is an approach to web tooling that seeks to solve for the traditonal, native web over vendor-specific interests. This is an especially important goal for a web community that is now fragmented into framework silos.
WebQit Community is an initiative to support an obvious community-wide paradigm shift for web-native development. We seek to drive community participation in new ideas for the web platform, and in all the projects that are revisiting much of the assumptions that brought us here, to explore new possibilities around just conventional web languages and APIs.
We're beginning this initiative by giving mentions to the actionable discussions from around the web that are painting this future of the web. It'll be nice to see the whole picture from one place.
Taste the future today from an ecosystem of open source tooling that explores the web-native approach to engineering modern web applications. It comes bringing all of the goodness of the native web platform and the traditional paradigms that have historically been traded.
We're iterating really fast - fast going from experimental to stable - on all the new possibilities we are exploring around conventional web languages and APIs, and the traditional web.
Contributions are welcome on each project! Help report typos and bugs via github issues, or submit a fix. Contributions are taken promptly and are well-acknowledged!
Taste the future today from an ecosystem of open source tooling that explores the web-native approach to engineering modern web applications. It comes bringing all of the goodness of the native web platform and the traditional paradigms that have historically been traded.
We're iterating really fast - fast going from experimental to stable - on all the new possibilities we are exploring around conventional web languages and APIs, and the traditional web.
Contributions are welcome on each project! Help report typos and bugs via github issues, or submit a fix. Contributions are taken promptly and are well-acknowledged!
Start on a clean slate, in zero-abstraction, zero-config, and zero-dependency. Develop and deploy anything from a simple 'Hello World!' to a rich web and mobile experience.
Visit the docs for an overview, the commands and usage guides.
Also, join the Github Discussions for OOHTML.
Help report bugs, or request features; or join in the development.
The MIT license.
It's a good practice to locate certain project files in conventional places. Webflo is thus able to automatically identify them at runtime. Here's an overview (keep in mind that everything below is optional, and/or can be renamed):
Let's now see what goes into each directory, and how they're all related.
/public DirectoryIf you intend to have static files (like images or CSS files) that should be served automatically, place them in this directory.
Your application's start page - index.html - should also be here.
/public/index.html - Try add some Hello World greeting.Now, when you start the Webflo server and navigate to http://localhost:3000/ (or http://localhost:3000/index.html) on your browser, the start page is shown.
webflo startEnsure that you are at your project root
webflo-appin the terminal to run the above Webflo command, and subsequent ones.
Now, if all you're creating is a static site, your work ends in this directory!
Webflo serves static files by simply mapping URL paths to filesystem paths. For example, the request URL / (or /index.html) would be mapped to the file /public/index.html, and the request URL /products (or /products/index.html) would be mapped to the file /public/products/index.html, and so on.
/server DirectoryIf you intend to have JavaScript files that handle dynamic routing on the server, place them in this directory.
/server/index.js - This is a server-side route handler.Now, what happens is, when you navigate to http://localhost:3000/ (or http://localhost:3000/index.html) on your browser, the route handler in index.js is hit first with the HTTP request. It then decides to either return its own response (in object format) or simply allow the request to flow to the default /public/index.html file, in which case an HTML response is returned.
/serverindex.js; continue?/public if exists; match index.htmlSo, route handlers can both return response data of their own and act as a gateway for the request/response flow. As we will see shortly, response data returned from route handlers can either serve as automatic JSON (API) responses or get rendered into the default /public/index.html file and returned as a rendered HTML response.
So far, with just two files - /public/index.html and /server/index.js - we can already return either of three responses for the URL http://localhost:3000/: a JSON API response, a static HTML response, or a dynamically-rendered HTML response. Code examples ahead.
Now, if all you're creating is a traditional server-side application or simply an API backend, your work ends in this directory! Routing is covered in the next section. And here are server-side routing examples.
/client DirectoryIf you intend to have JavaScript files that handle routing (e.g navigation requests) in the browser, place them in this directory.
/client/index.js - This is a client-side route handler.Next, run a Webflo command that automatically builds these files into a single script that you can include on your /public/index.html page.
webflo buildClient builds are covered later on. But let's assume for now that the generated JavaScript file is now included in the HTML page.
Now, what happens is, when you navigate to http://localhost:3000/ (or http://localhost:3000/index.html) on your browser, this client-side route handler is hit first with the HTTP request. It then decides to either return an in-browser response data that's rendered to the UI or simply allow the request to flow to the server - all while preventing the browser from performing a page reload.
/clientindex.js; continue?/server if existsindex.js; continue?/public if exists; match index.htmlAs we will see, being able to either return an in-browser response data or act as a gateway for the request/response flow is a powerful way to create fast and smooth client-side experiences.
At this point, with just three files - /public/index.html, /server/index.js and /client/index.js - we can already have either a static site, an API backend, a server-side app, a client-side app, or a combination of all of these. Code examples ahead.
Okay, if all you're creating is a client-side application, your work ends in this directory! Routing is covered in the next section. And here are client-side routing examples.
/worker DirectoryWhat happens here is quite advanced and you can ignore this until you really need it. But if you already know about application Service Workers and intend to enhance your app's client-side experience with Service Workers, Webflo lets you implement routing at the service-worker level, and you place your route handlers in this directory.
/worker/index.js - This is a worker-level route handler.Next, run a Webflo command that automatically builds these files into a single script that will form part of the service worker file for your page.
webflo buildWorker builds are covered later on. But let's assume for now that the generated JavaScript file is now part of the service worker file for your page.
Now, what happens is, when you navigate to http://localhost:3000/ (or http://localhost:3000/index.html) on your browser, and the HTTP navigation request is passed on from the initial client-side route handler /client/index.js, where exists, the request next enters the Service orker layer and hits this route handler. This handler then decides to either return an in-browser response data that's rendered to the UI or simply allow the request to finally flow to the server.
/client if existsindex.js; continue?/workerindex.js; continue?/server if existsindex.js; continue?/public if exists; match index.htmlWoohoo! With a combition of just four files - /public/index.html, /server/index.js, /client/index.js and /worker/index.js - we can already have any type of application with great offline experiences.
It is even just possible to build an entire app out of the
/workerdirectory alone, if all you're building is a client-side, offline-capable app! Routing is covered in the next section. And here are worker-level routing examples. Service Workers are covered in detail in the Progressive Web Apps (PWA) tutorial.
Webflo lets us follow the traditional filesystem layout for a project. The concept of routing is simply drawn on this layout. It is all about the request/response flow and what happens along the path it takes. Webflo's skillfulness with flows is probabbly the best thing about its name.
If we've grasped the concept of project layout above, we've done routing in Webflo, basically. What we will now cover is orchestrating routes along the request/response flow.
In Webflo, we can implement routing at vertical layers between the client and the server. And in a routing layer, we can lay out route handlers in horizontal steps for URL paths of more than one level (e.g /a/b/c).
Each directory discussed in the Project Layout section above lives at a point on a vertical path between the client and the server. Here's that layout now in the order of request/response flow.
/client if exists; continue?/worker if exists; continue?/server if exists; continue?/public if exists; match a static file.As seen in the Project Layout section above, the type of application you're building will determine where you choose to implement routing. It could be just client-side routing, just server-side routing or fullstack routing in any combination of it, as we will see soon.
In a routing directory, we can lay out route handlers in a way that represents the structure of the URLs that they will handle. If we chose to do routing in the /server directory, for a example, we would place a route handler at /server/index.js to handle the request URL /, and a route handler at /server/products/index.js to handle the request URL /products, and so on. So, each level of an URL path (e.g /a/b/c) is a place to implement a route handler.
But in Webflo, requests are processed in steps along an URL path, that is, are made to flow through every handler in the route path until it hits the final handler. Here, the request URL /products would actually flow like this:
/server/index.js; continue?/products/index.js; return response.This is called step routing, and its the most-empowering way to orchestrate routes.
Route handlers are index.js files that are laid out in the routing directory to handle the application's request/response flow. The most important content of these files are a simple function that is exported as the default export of the file.
export default function(flo, received, next) {
}This function is what is called when a request flow hits a route.
Of the three parameters of a route handler, the next parameter is what it uses to forward a request, if it chooses to. This is the concept of flow control.
Given the following route hierarchy…
/server/index.js/products/index.jsHere is how our route handlers could look:
file: /server/index.js
export default function(process, received, next) {
if (next.pathname) {
return next();
}
return { title: 'Hello World', };
}file: /server/products/index.js
export default function(process, received, next) {
if (next.pathname) {
return next();
}
return { title: 'Our Products', };
}In the first handler, we started by asking if the route path has another step ahead. For a path like /products, the answer is yes, and the flow is forwarded to the next handler in the path.
In the second handler, we again started by asking if the route path has another step ahead. This time, the answer is no, and reponse data is returned here for the request.
Flow control is especially important for root-level handlers, i.e handlers that handle the application's root URL /, since they act as the gateway to all of the application's routes - both static and dynamic routes.
Given the following layout…
/server/index.js/public/index.html/assets/main.cssThe request URL /index.html would flow this way:
/server/index.js; continue? Yes! (test next.pathname: 'index.html'; then next())/public; match index.htmlWhile, the client request URL / would flow this way:
/server/index.js; continue? No! (test next.pathname: ''; return { title: 'Hello World', })This way, static file URLs are properly allowed at this critical point in the application's URL-handling. Also noteworthy is that the static file URL /index.html is still handled differently from the path URL /. Thanks to next.pathname and next().
As we would expect, if we had no route handlers intercepting the request, both URLs -
/index.htmland/- would be mapping directly to/public/index.html.
Try figuring out on your own the flow for the URL
/assets/main.css.
As a general rule, it is good to always use next.pathnameand next() to properly manage the flow, even when writing the last handler for a given route hierarchy. There are many important advantages to this:
Given an earlier example, while the last handler in our route hierarchy is designed for the URL /products, our flow control code in there would make an unexpected, extended URL like /products/specials trigger the next() function; and since nothing like that really exists ahead, an empty respone would be returned, which Webflo gracefully translates into a 404 HTTP response. Without that check in place, an invalid URL would be returning a falsely-valid response.
Furthermore, if, or when, we do eventually place a handler there for that level of the route path, our flow control code in the current handler would have already ensured that requests can flow through to the new level.
Or, where another routing layer exists below the given routing layer, our flow control code in this last handler for the route would be forwarding those requests to the next layer.
In the layout below, the request URL /products/specials that is non-existent in the upper routing layer is actually existent in the lower routing layer.
/server/index.js/products/index.js/public/products/specials/index.htmlCalling next() at the last handler for the URL will forward the flow off the /server routing layer into the /public routing layer, and the HTML file is served for the URL.
Here is how that would flow:
/server/index.js; continue? Yes! (test next.pathname: 'products/specials/index.html'; then next())/products/index.js; continue? Yes! (test next.pathname: 'specials/index.html'; then next())/public; match products/specials/index.htmlA side benefit we've enjoyed with this
products/specialsURL is the convenience of having it begin life as a static route until we can make it dynamic by creating a route handler for it.
While being used to forward a request, the next() function can help to pass on anything to the next handler.
file: /server/index.js
export default function(process, received, next) {
if (next.pathname) {
return next({ userId: 1 });
}
return { title: 'Hello World', };
}file: /server/products/index.js
export default function(process, received, next) {
if (next.pathname) {
return next(received);
}
if (received.userId) {
// Show recommended products
return { title: 'Recommended Products For You', };
}
return { title: 'Our Products', };
}In the first handler, we passed an object via the next() function. In the second handler, we received it on the received parameter.
Parameter passing is a great way to implement one source of truth for subsequent handlers in the route hierarchy. Think authentication, certain database or external API queries, etc. Doing these at the earliest level in the route hierarchy and passing tokens or objects down is a perfect way to avoid repeating code down the hierarchy.
process ObjectWhen called, route handlers recieve very useful information about the ongoing HTTP process. This and a few other metadata are passed together as an object into the first parameter of the handler - the process parameter.
Welcome to the Webflo documentation. We hope you find it easy to understand and navigate.
If you have questions about anything related to the Webflo, you're always welcome to ask on our GitHub Discussions.
The Webflo API reference.
class NavigationEvent {}This is the NavigationEvent that is fired on every request which route handlers receive on their event parameter.
url: URL - An object representing the request URL. (See class URL.)request: Request - The incoming request object. (See interface Request.) On the client side, this would be an extended instance of the standard Request interface. On the server side, this would be an extended instance of node.js's http.IncomingMessage class.Response: Class - A class for instantiating a new reponse. (See class event.Response.)Route handlers are simple export functions that are designed to intercept a request and return a response. Webflo sticks with one way to define route handlers across all routing layers.
Syntax
export default async function(event, app, next) {
}The syntax also supports naming a handler after a specific HTTP method, where that level of modularity is needed.
export async function get(event, app, next) {
}export async function post(event, app, next) {
}export async function del(event, app, next) {
}export async function put(event, app, next) {
}The default handler will always be called where no method-specific handlers exist.
Parameters
event: NavigationEvent - A NavigationEvent instance fired for the request.
app: Any - Any incoming value being passed by a parent handler. (See Parameter Passing.)
next: Function - The function to call to forward a request.
Syntax
var response = await next([app[, pathname]]);Parameters
app: Any - An optional value to pass to child handler. (See Parameter Passing.)pathname: String - An optional pathname specifying the direction of the flow. (See Route Bending.)Return Value
response: Promise<Object|event.Response> - A promise that resolves to the return value from child handler. (Handler return values just ahead.)Contextual Parameters
this.stepname: String - The exact name of the current step in the URL path.this.pathname: String - The pathname to the current step in the URL path.this.dirname: String - (Available only in server-side handlers.) The file name of the current handler.this.env: Object - (Available only in server-side handlers.) Any environmental variables defined in an .env file at project root.this.layout: Object - (Available only in server-side handlers.) An object that exposes the filesystem layout of the project as configured via $ webflo config layout.next.stepname: String - The exact name of the next step in the URL path.next.pathname: String - The pathname for the rest of the steps in the URL path.Return Value
Any - A plain JavaScript object or array (JSON-stringifiable) may be returned and will translate to the reponse data (stringified JSON) where the request is an API Call, or the rendering data where the request is a Page Request. (For example: return { title: 'Home | Co' }). Any other value, e.g. 0, may be returned, and Webflo will try to send it as-is.undefined - An undefined will translate to a 404 - Not Found HTTP response.Response - An instance of event.Response with a .body property being any of the above may be returned. (For example: return new event.Response({ body: { title: 'Home | Co' }, headers: {...} })).Promise - A promise that resolves to any of the above may be returned. (Route handlers can thus be an async function.)interface Request {}This is an interface that is additionally implemented by the incoming request instances that route handlers receive on their event.request parameter. (Client-side event.request objects are an instance of the standard Request interface. Server-side event.request objects are an instance of node.js's http.IncomingMessage class.)
cookies: Object - An object representing the request cookies. This is an object model of the submitted cookies. Cookie names in path notation are written to their equivalent path in the object. For example, the cookie q7[sublevel1]=deepvalue will be accessed as event.request.cookies.q7.sublevel1;accepts: Object - (Available only in server-side instances.) An accepts object for the request as returned by Accepts.parse(): <Promise>Object - This returns a promise that resolves to the request payload.
Syntax
let submits = await event.request.parse();Return Value
submits: Object - The parsed request data. (See Submits below.)event.request objects, see the standard Request interface.event.request objects, see node.js's http.IncomingMessage class.This is the object returned by await event.request.parse(), containing the below details of the request payload.
Content-Type header of the request. This would be form-data for Content-Type === 'application/x-www-form-urlencoded' or Content-Type === 'multipart/form-data', json for Content-Type === 'application/json', plain for Content-Type === 'text/plain', other for other Content-Type values.FormData for submits.type === 'form-data', JSON (object, array, or primitive) for submits.type === 'json', plain text for submits.type === 'text', Uint8Array for submits.type === 'other'.submits.payload, where submits.payload is FormData or where submits.payload is a JSON object or array.submits.payload, where submits.payload is FormData.The inputs and files properties above are object models of the submitted fields. Field names in path notation are written to their equivalent path in the object.
The fields below…
<input name="user[profile][visibility]" type="checkbox" value="public" />
<input name="user[profile][pics][]" type="file" multiple />…will be accessed in the application as:
lat payload = await event.request.parse();
let profileVisibility = submits.inputs.user.profile.visibility;
let profilePics = submits.files.user.profile.pics;class Response {}This class is used for returning responses from route handlers. It is available to route handlers on their event.Response parameter.
Returning responses with this class allows a handler to include an HTTP status code and some HTTP headers.
export default async function(event, app, next) {
if (next.stepname) {
return next();
}
return new event.Response({
status: 200,
headers: { 'Content-Type': 'application/json', },
body: { prop1: value1, }
});
}But in many cases, creating an event.Response instance will not be necessary as Webflo will dynamically figure out an appropriate HTTP status code along with a Content-Type header for the response as detailed in: API Calls and Page Requests. Here, returning the plain data object will just suffice.
export default async function(event, app, next) {
if (next.stepname) {
return next();
}
return { prop1: value1, };
}With the first handler above returning a
Content-Typeheader, no automatic content negotiation will be made by Webflo.
let response = new event.Response(params);Parameters
params: Object - The response parameters.
Fundamental parameters
status: Number - An HTTP response code.
headers: Object - HTTP header definitions, in the format: { <Header-Name>: <header-value> }. (For the Set-Cookie header, <header-value> must be an object - as shown below.)
body: Any - The respone payload.
Occasional parameters
filename: String - Required where body is a File object read from the filesystem.
The constructor 's params automatically become instance properties. See Header Shortcuts below for predefined properties.
setHeader(name, value)This method sets an HTTP header.
Parameters
name: String - The header name - case-insensitive.value: Any - The header value. (For the Set-Cookie header, this must be an object - as shown below.)Return Value
this - The response instance.getHeader(name)This method retrieves an HTTP header.
Parameters
name: String - The header name - case-insensitive.Return Value
Any - The header's value.This class exposes certain properties that make it easier to set and access common HTTP headers. Values assigned to these properties are automatically translated to the corresponding headers under the hood; values obtained from these properties are automatically taken from those same headers.
The Content-Type header may be set and accessed using the contentType property of the response object, and may be provided as the contentType field of the constructor's input.
let response = new event.Response({
body: 'Hello Webflo!',
contentType: 'text/plain'
});
console.log(response.headers);
// { 'Content-Type': 'text/plain' }
console.log(response.contentType);
// text/plainThe Location header may be set and accessed using the redirect property of the response object, and may be provided as the redirect field of the constructor's input.
let response = new event.Response({
redirect: '/new-location',
status: 301,
});
console.log(response.headers);
// { Location: '/new-location' }
console.log(response.redirect);
// /new-locationWhere no status code is given, the 302 (temporary redirect) is used.
The Content-Disposition header may be set and accessed using the download property of the response object, and may be provided as the download field of the constructor's input.
let response = new event.Response({
body: blob,
download: true,
});
console.log(response.headers);
// { 'Content-Disposition': 'attachment' }
console.log(response.download);
// trueA filename may be added to the download directive.
response.download = 'filename.jpg';
console.log(response.headers);
// { 'Content-Disposition': 'attachment; filename="filename.jpg"' }
console.log(response.download);
// filename.jpgWhere download is set to false, the default value inline for the header is used.
response.download = false;
console.log(response.headers);
// { 'Content-Disposition': 'inline' }
console.log(response.download);
// falseThe Cache-Control header may be set and accessed using the cacheControl property of the response object, and may be provided as the cacheControl field of the constructor's input.
let response = new event.Response({
body: 'John Doe.',
cacheControl: 'no-store',
});
console.log(response.headers);
// { 'Cache-Control': 'no-store' }
console.log(response.cacheControl);
// no-storeThe Access-Control-Allow-Origin header may be set and accessed using the cors property of the response object, and may be provided as the cors field of the constructor's input.
let response = new event.Response({
body: 'John Doe.',
cors: '*',
});
console.log(response.headers);
// { 'Access-Control-Allow-Origin': '*' }
console.log(response.cors);
// *Where cors is set to true, the wildcard * is used. Where false, an empty string '' is used.
The Set-Cookie header may be set and accessed using the cookies property of the response object, and may be provided as the cookies field of the constructor's input.
let response = new event.Response({
body: 'John Doe.',
cookies: {
cookie1: 'value1',
cookie2: { value: 'value12' },
},
});
console.log(response.headers);
// { 'Set-Cookie': { cookie1: 'value1', cookie2: { value: 'value12' } } }
console.log(response.cookies);
// { cookie1: 'value1', cookie2: { value: 'value12' } }Cookie attributes may be set - in camel-case names.
response.cookies.cookie2.secure = true;
response.cookies.cookie2.sameSite = 'Strict';
response.cookies.cookie2.maxAge = 2592000;Where value is set to false and no maxAge attribute is set, a maxAge of 0 is implied, effectively expiring the cookie immediately.
class URL {}This is an interface that is additionally implemented by the request URL objects that route handlers receive on their event.url parameter. (Both client-side and server-side event.url objects are instances of the standard URL interface.)
query: Object - An object model of the URL query parameters. This maintains a live, two-way relationship between itself and the .search string property of its base URL object. Changes made on one end are automatically reflected on the other.
Case:
event.url.href:https://example.com/path?q1=value1&q2=value2
Modify the query string:
event.url.search += '&q3=value3';
console.log(event.url.query);
// { q1: 'value1', q2: 'value2', q3: 'value3' }Replace the query object:
event.url.query += { q4: 'value4', q5: 'value5', };
console.log(event.url.search);
// ?q4=value4&q5=value5Modify the query object in-place:
event.url.query.q6 = 'value6';
delete event.url.query.q4;
console.log(event.url.search);
// ?q5=value5&q6=value6Additionally, query parameter names in path notation are written to their equivalent path in the object model.
Case:
event.url.href:https://example.com/path
Set an path parameter that resolves to an object:
event.url.search = 'q7[sublevel1][sublevel2]=deepvalue';
console.log(event.url.query);
// { q7: { sublevel1: { sublevel2: 'deepvalue' } } }Set an path parameter that resolves to an array:
event.url.search = 'q7[sublevel1][sublevel2][]=deepvalue';
console.log(event.url.query);
// { q7: { sublevel1: { sublevel2: [ 'deepvalue' ] } } }URL interface.The Webflo Command-Line reference.
> webflo config> webflo build> webflo deploy> webflo help> webflo :serverRoutes in Webflo can be designed for different types of requests and responses.
HTTP requests are capable of specifying (using the Accept header) in which format a response should be returned by the server. Webflo makes it possible to use this medium to access the data component of a route differently from its HTML component. Routes in Webflo are therefore designed to treat data as a standalone component from HTML, enabling reusability for both.
A route handler would simply concern itself with data.
webflo-app
├⏤server
├⏤index.js
export default function(event, app, next) {
if (next.stepname) {
return next();
}
return { title: 'Home | Co' };
}The data returned would be returned as-is - a JSON response - where the Accept header of the request does not match text/html but matches application/json. This would be taken as an API call. The response header is automatically given Content-Type: 'application/json'.
For API endpoints, the above would be everything for the request and response flow. For routes that will deliver a rendered HTML response, the HTML to render would be a standalone file in the /public directory.
webflo-app
├⏤public
├⏤index.html <html><head></head><body>...</body></html>Webflo knows to find a /public/index.html file for rendering the data returned by /server/index.js. Nested routes are given the choice to either have their own index.html file at the corresponding location in the /public directory or inherit the closest one up in their ancestrial line.
A rendered HTML page is therefore returned where the Accept header of the request matches text/html (as a web browser would normally have it for page navigation). This would be taken as a page request. The response header is automatically given Content-Type: 'text/html'.
The general rule for this content negotiation therefore becomes: a rendered HTML response for page requests (Accept header matching text/html), and a JSON response for API calls (Accept header not matching text/html but matching application/json).
An automatic
Accept: application/jsonheader - just ahead - can always be used on API-only endpoints to tell Webflo to always return a JSON response.
As for the static index.html file in the /public directory, being in the /public directory means that a direct access would still be possible, as it is with all the files in this directory. But route handlers will have a chance to intercept this direct access, where actually necessary.
webflo-app
├⏤server
│ ├⏤index.js
│ export default function(event, app, next) {
│ if (next.stepname && next.stepname !== 'index.html') {
│ return next();
│ }
│ // Both URLs "/" and "/index.html" will lead here
│ return { title: 'Home | Co' };
│ }
├⏤public
│ // No more direct access to this file
├⏤index.html <html><head></head><body>...</body></html>Overall, this approach lets us reuse more and repeat less. A route handler alone gives us data; an index.html file alone gives us static HTML; a combination gives us the choice of either data, static HTML or rendered HTML - in just simple content negotiation.
Now, where a route handler returns a value other than an array or an object, no content negotiation takes place (and no automatic Content-Type header). Webflo will try to make a string response of the returned value.
Route handlers may return an instance of the event.Response class as a response. And Webflo's automatic content negotiation can still take place.
export default async function(event, app, next) {
if (next.stepname) {
return next();
}
return new event.Response({
body: { title: 'Home | Co' },
});
}The response data will be available in the .body property of the instance. Parent handlers may test for this type of response object to obtain the actual reponse data.
export default async function(event, app, next) {
if (next.stepname) {
let childResponse = await next();
if (childResponse instanceof event.Response) {
childResponse = childResponse.body;
return { ... };
}
}
return { ... };
}HTTP status codes and headers may be returned with the instance via the status and headers fields respectively.
return new event.Response({
status: 200,
headers: { 'Content-Type': 'application/json' },
body: { title: 'Home | Co' },
});The Content-Type header is a special header that will mark the response as final; no automatic content negotiation will take place. This is also the case with the Location header, used to initiate a redirect.
Header Shortcuts may also be used to more conveniently set and access common headers.
let response = new event.Response({
headers: { 'X-Custom-Header': 'some value' },
body: true, // JSON Boolean value
});
response.contentType = 'application/json';
response.cacheControl = 'no-store';console.log(response.headers);
// { 'X-Custom-Header': 'some value', 'Content-Type': 'application/json', 'Cache-Control': 'no-store' }
console.log(response.contentType);
// 'application/json'
console.log(response.cacheControl);
// 'no-store'And the .setHeader() and .getHeader() methods can always be used to set and access headers in a case-insensitive manner.
console.log(response.getHeader('x-custom-Header'));
// 'some value'Put together, any type of response can be conveniently returned this way.
Now, where a route handler returns nothing, Webflo will know to return a 404 HTTP response.
HTTP request and response cycles are generally controlled by headers. Webflo offers the easiest way to work with headers.
Request headers can always be sent by a HTTP client or browser, and response headers can always be returned by route handlers. But in Webflo, it is possible to get certain headers automatically added to these requests and responses. These automatic headers are defined on the command line using $ webflo config headers.
The underlying JSON config file .webqit/webflo/config/headers.json may be directly edited. Entries go into the entries array field as shown below.
{
"entries": [
{
"type": "request", // Or "response"
"url": "/api/v1", // Or a glob pattern
"name": "Accept", // Or any other header
"value": "application/json"
}
]
}Fields
type: String - The header type. This can be one of two values: request for request headers, response for response headers.
url: String - The URL on which the header takes effect. This can be a glob pattern. For example, the value * would mean any URL, and the value *.js would mean any URL ending as .js, and so on. (See the Micromatch documentation for a detailed glob syntax.)
name: String - The header name. This can take a convention that gets the header either appended or prepended to any existing declaration in the target headers list: the prefix + to append; the suffix + to prepend.
In the example above, the name Accept would set the value application/json as the Accept header of the incoming request; but +Accept would get it rather appended to any existing Accept header, and Accept+ would get it prepended.
value: String - The header value.
A redirect response header can always be returned by route handlers. But in Webflo, it is possible to get certain URLs automatically redirected as the requests enter the application. Automatic redirects are defined on the command line using $ webflo config redirects.
The underlying JSON config file .webqit/webflo/config/redirects.json may be directly edited. Entries go into the entries array field as shown below.
{
"entries": [
{
"from": "/old-url", // Or a glob pattern
"to": "/api/v1",
"reuseQuery": true, // false by default
"code": "302" // 301 by default
}
]
}Fields
from: String - The URL on which the redirect takes effect. This can be a glob pattern. For example, the value * would mean any URL, and the value *.js would mean any URL ending as .js, and so on. (See the Micromatch documentation for a detailed glob syntax.)
to: String - The destination URL. Where the from URL is a glob pattern that matches only the begining part of an incoming request URL, the final destination URL will be the to URL plus the rest of the incoming request URL.
For example, if the from URL is /old-url* and the to URL is /new-url, and the incoming request URL is /old-url/page, the final destination URL will be /new-url/page.
reuseQuery: Boolean - A flag that specifies whether to reuse the query parameters from the incoming request URL in the destination URL. Default is false.
For example, if the incoming request URL is /old-url/page?q=search-word, the final destination URL will be /new-url/page?q=search-word.
code: Number - The redirect code. This can be one of two values: 301 for a permanent redirect - the default, 302 for a temporary redirect.
Webflo also supports HTTPS redirects and
wwwsubdomain redirect. See$ webflo config serverfor details.
In Webflo, routing is filesystem-based. Here, we simply create a file on the filesystem and it automatically becomes available as an URL.
The application's root URL /, for example, would be implemented by creating an index file - <indexFile> - in a chosen routing directory - <routingDirectory>.
<routingDirectory>
├⏤<indexFile>Nested URLs like /shop would be implemented by creating the equivalent directory structure /<routingDirectory>/shop/<indexFile>.
<routingDirectory>
├⏤shop
│ ├⏤<indexFile>
├⏤<indexFile>The actual name for <routingDirectory> and <indexFile> will depend on the URL-handling facilities for the URL.
Depending on the type of application, a given URL can be internally handled either statically or dynamically. Webflo lets us define an application's URL-handling facilities in dedicated directories.
/public - for static files serving/server - for server-side routing/client - for client-side routing/worker - for worker-level routing/public DirectoryThis is where static files (like images or CSS files) are placed to be served automatically. (Implement this directory for an application that serves static content.)
The application's homepage /index.html, for example, can be served statically by simply placing an index.html file in the /public directory.
public
├⏤index.html - <html><head></head><body>Home | Co</body></html>Webflo automatically finds the
index.htmlfile where a path URL/is given.
/server DirectoryThis is where JavaScript files for server-side routing are placed. (Implement this directory for a server-side application, or an isomorphic application, or an API backend.)
The application's root URL /, for example, can be handled on the server by simply placing an index.js file in the /server directory.
server
├⏤index.js - export default function() { return { title: 'Home | Co' } }The data returned by these handlers are either rendered into the correspnding
index.htmlpage from the/publicdirectory - Server-Side Rendering, or returned as a JSON response - API Responses. TheAcceptheader of the request is used to determine this. (Learn more in Requests and Responses.)
/client DirectoryThis is where JavaScript files for client-side routing are placed. (Implement this directory for an application that will deliver a rich client-side experience.)
The application's root URL /, for example, can be handled on the client (the browser) by simply placing an index.js file in the /client directory.
client
├⏤index.js - export default function() { return { title: 'Home | Co' } }The data returned by these handlers are rendered into the already running page in the browser - Client-Side Rendering.
/worker DirectoryThis is where JavaScript files for service-worker-level routing are placed. (Implement this directory for an application that will have special offline capabilities.)
The application's root URL /, for example, can be handled in the browser's service-worker layer by simply placing an index.js file in the /worker directory.
worker
├⏤index.js - export default function() { return { title: 'Home | Co' } }The data returned by these handlers are rendered into the already running page in the browser - Client-Side Rendering. (These handlers will also be able to intercept certain other browser-generated requests that cannot be intercepted by client-level handlers.)
URL-handling in Webflo is like an assembly line. Route handlers that are related by a given URL are able to communicate to fullfil a request with a dynamically composed response.
Route handlers recieve a next() function that they can call to get a request moving in this assembly line.
In real life, the equivalent directory structure for nested URLs creates a parent-child relationship. URL handlers are implicitly subject to this relationship.
<routingDirectory>
├⏤shop
│ ├⏤index.js
├⏤index.jsWebflo follows an approach that gets a request going from a parent handler to a child handler. This creates a flow-through effect that lets us take advantage of this relationship for new routing capabilities.
A request for the URL /shop, for example, would flow through two route handlers - the first two handlers below.
file: /server/index.js
export default async function(event, app, next) {
if (next.stepname) {
let shop = await next();
return { ...shop, title: shop.title + ' | Co', };
}
return { title: 'Home | Co' };
}
file: /server/shop/index.js
export default async function(event, app, next) {
if (next.stepname) {
return next();
}
return { title: 'Shop', data: ... };
}
file: /server/shop/products/index.js
export default async function(event, app, next) {
if (next.stepname) {
return next();
}
return { title: 'Products', data: [
...
] };
}In the first handler, we started by asking next.stepname if the URL has another step ahead. For an URL like /shop, the answer is yes, and the request is exchanged for the child's data. The parent handler thus intercepts both the request going into the child and the response coming back from the child.
In the second handler, we again started by asking next.stepname if the URL has another step ahead. This time, the answer is no, and reponse data is returned here for the request.
As the URL /shop terminates on the second handler, an outright call to next() does not get the request to the third handler. Rather, a fall-through effect happens.
In real life, each of Webflo's routing directories above represents a point between the browser and the server across which a request flows. Put together, they give us the following URL-handling layers in the given order.
/client ⥮/worker ⥮/server ⥮/public ⥮Webflo makes it possible to intercept a request in one layer and forward it down to the next layer. For example, a navigation to the root URL / can be intercepted by the client-side handler /client/index.js and forwarded down - to be further intercepted by the server-side handler /server/index.js, where exists. This creates a fall-through effect that lets us combine powerful cross-stack routing capabilities on a single URL.
A request for the root URL /, for example, would fall through on a call to next().
file:
/client/index.js
export default async function(event, app, next) {
let remoteContent = await next();
return remoteContent ? remoteContent : { title: 'Offline Home | Co' };
}file:
/server/index.js
export default async function(event, app, next) {
if (next.stepname) {
let shop = await next();
return { ...shop, title: shop.title + ' | Co', };
}
return { title: 'Home | Co' };
}Put together, requests fall through layers in the following flow:
-> enter `/client` if exists
-> call `index.js`; return response here? or continue-> enter `/worker` if exists
-> call `index.js`; return response here? or continue-> enter `/server` if exists
-> call `index.js`; return response here? or continue-> enter `/public` if exists; find and return `index.html`Now, with the /public directory being the last in the stack, a fall-through effect will be especially important for an application that will both implement dynamic routes and serve static content. Static file requests must be forwarded in order to reach the /public directory.
The handler below has been designed to ensure that the URL /logo.png and /index.html, and in fact, other URLs that are not exactly terminating on it, can flow through and fall through.
webflo-app
├⏤server
│ ├⏤index.js
│ export default function(event, app, next) {
│ if (next.stepname/* logo.png or index.html, or other */) {
│ return next();
│ }
│ return { title: 'Home | Co' };
│ }
├⏤public
├⏤index.html
├⏤logo.pngThe above also demonstrates that the URLs / and /index.html would mean two different things where a route handler exists.
/ would terminate on the handler, the URL /index.html would flow through and fall to the /public directory and a static file is served./ was made with an Accept header that matches text/html, Webflo will know to render the handler's response into the index.html file of the URL and return a rendered HTML response. Otherwise, Webflo will know to return the handler's response as-is - a JSON response. This is detailed in Requests and Responses,Route handlers are simple functions that are designed to handle incoming requests on an URL and return response data. The standard syntax for a route handler and their contextual parameters and return values are detailed in the Route Handlers API section; and it is all simple to reason about: route handlers use the this.pathname and this.stepname to know its place in the current URL, the next.pathname and next.stepname to ask about a forward flow, and the next() function to forward a request.
While being used to forward a request, the next() function can help to pass on anything to the next handler.
file:
/server/index.js
export default function(event, app, next) {
if (next.stepname) {
return next({ userId: 1 });
}
return { title: 'Home | Co' };
}file:
/server/shop/index.js
export default function(event, app, next) {
if (next.stepname) {
return next(app);
}
if (app.userId) {
// Show recommended products
return { title: 'Shop Plus Recomendations', };
}
return { title: 'Shop', };
}In the first handler, we passed an object with the next() function. In the second handler, we received it on the app parameter. (The app parameter is always empty for root URL handlers as they have no parent handler.)
Parameter passing is a great way to implement one source of truth for every handler on an URL. Think authentication states, certain database or external API tokens, etc, that would be needed at different levels in the handler hierarchy.
While a call to next() automatically takes the request to the next handler in line for an URL, a redirect to an adjacent handler can be made. The next() function accepts a second parameter that specifies in which direction to go.
file:
/server/docs/index.js
export default function(event, app, next) {
// Serve the highest version of the docs for /latest
if (next.stepname === 'latest') {
return next(app, next.pathname.replace('latest', 'v2'));
}
return next(app);
}file:
/server/docs/v2/index.js
export default function(event, app, next) {
return { title: 'Docs: V2', };
}file:
/server/docs/v1/index.js
export default function(event, app, next) {
return { title: 'Docs: V1', };
}A handler can be designed for a step that is dynamically resolved from the request URL. This generic point in the layout is called a wildcard step. Wildcard steps are always a hyphen -. (Notice the - hyphen in the directory below.)
<routingDirectory>
├⏤docs
│ ├⏤-
│ │ ├⏤index.js
│ ├⏤index.js
├⏤index.jsAbove, the handler at /server/docs/-/index.js will be called for all matching URLs - like /docs/v1, /docs/v2/getting-started/overview, etc.
file:
/server/docs/-/index.js
export default function(event, app, next) {
// The resolved stepname from the request URL will be available as this.stepname
console.log(this.stepname); // v2
console.log(next.stepname); // getting-started
console.log(next.pathname); // getting-started/overview
}Every Webflo project starts on an empty directory that you can create on your machine. The command below will make a new directory webflo-app from the terminal and navigate into it.
mkdir webflo-app
cd webflo-appWith npm available on your terminal, the following command will install Webflo to your project:
System Requirements: Node.js 12.0 or later
$ npm i @webqit/webfloThe installation automatically creates a package.json file at project root, containing @webqit/webflo as a project dependency.
{
"dependencies": {
"@webqit/webflo": <webflo version>
}
}Other important definitions like project name, package type, and aliases for common Webflo commands will also belong in this file.
{
"name": "webflo-app",
"type": "module",
"scripts": {
"start:dev": "webflo start --dev",
"build": "webflo build"
},
"dependencies": {
"@webqit/webflo": <webflo version>
}
}All is now set! The commands npm run start:dev and npm run build will be coming in often during the development process.
Other Webflo commands will also be used at some point. For these, we will be prefixing the command to run with npx; e.g. npx webflo help.
A global installation of Webflo wouldn't require aliases in
package.jsonor thenpxprefix to run. To install Webflo globally, runnpm installwith the-g(or--global) flag:npm i -g @webqit/webflo.
To be sure Webflo is listening, run npx webflo help; an overview of available commands will be shown.
The start page of our sample app could be a simple index.html file served statically. This would go into the /public directory of the app. (More about project layout in Routing.)
/public/index.html - <html><head></head><body>Hello Webflo!</body></html>Now, when you start the Webflo server and navigate to http://localhost:3000/ (or http://localhost:3000/index.html) on your browser, the start page is shown.
$ npm run start:devBe sure to give Webflo a better "Hello!" with a more beautiful start page.
As with every project that might be heading out of its local development environment, certain files, folders or parameters for Webflo applications may need to be excluded from upstream repositories. And it is good to remember these environmental factors early.
.env FileAn .env file is commonly used to maintain environment-specific varaiables for an application. Consider using this file to keep any sensitive values that your application might need, e.g. database credentials. This file would be kept local using the .gitignore file below. The ignore rule would be: .env.
Consider paring the .env file with an .env.example file - written with no actual values, and for simply providing an example of what might be in the .env file. This file would be what goes to other deployment environments.
To edit the .env file from the command line, run $ webflo config variables. Add the flag --env=example to explicitly edit the .env.example file.
When creating the .env file for the first time, Webflo will try to guide you using the variable names and available example values in the .env.example file, where exists.
.webqit DirectoryAll WebQit command-line interfaces maintain certain command-line edits in the WebQit-specific folder: .webqit. Webflo's own edits go into the ./.webqit/webflo directory; and these files are to be kept local using the .gitignore file below. The ignore rule would be: .webqit.
The --env=example flag may be used to create example copies of these configurations - written with no actual values, and for simply providing an example of what might be in the actual configuration. Edits made with $ webflo config variables --env=example, for example, will be written to the file: ./.webqit/webflo/variables.example.json. These example copies are what goes to other deployment environments. The allow rule would be: !.webqit/**.example.json.
.gitignoreFileThis file should now be part of your project. And an important folder to ignore is the node_modules folder. Together with the environment-specific files above, your .gitignore file could be looking similar to the below:
node_modules
.env
.webqit
!.webqit/**.example.jsonFeel free to add more rules as needed.
Continue to learning the fundamentals.
Webflo is the universal JavaScript framework for Web, Mobile, and API Backends, and the single tool that takes you from development, to deployment, to continous delivery. The Webflo experience is: all of the possibilities delivered in a long-story-short approach!
Take an overview!
Every Webflo project starts on an empty directory that you can create on your machine. We are creating one below - named webflo-app - and navigating into it on the terminal.
mkdir webflo-app
cd webflo-appNext is to have Webflo installed, following the installation guide. This makes the webflo command available on the terminal. And that is all the setup required!
Webflo is a command-line tool. So the installed files won't be showing up anywhere in your workspace.
Any project will normally live in files and folders. Webflo lets us follow a layout that just defines the capabilities of the application.
The following directories are used as the application's URL-handling facilities.
/public - for static files serving/server - for server-side routing/client - for client-side routing/worker - for worker-level routingAny other directory (e.g. /src) may exist here at root level for other purposes.
Main Topic: Routing