|
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164 |
- # webframe
-
- Webframe is a small and dependency free web application framework.
-
- ## Usage
-
- Install:
-
- ``` bash
- npm install --save webframe
- ```
-
- Use:
-
- ``` JavaScript
- var webframe = require("webframe");
- var app = new webframe.App();
- ```
-
- Or from the command line:
-
- ``` Bash
- npm install -g webframe
- webframe [directory]
- ```
-
- The file example.js contains an example of a small web application.
-
- ## Why a new web framework?
-
- A new installation of express is 2.3 megabytes. You end up with 42 dependencies
- in your node\_modules directory. The Koa framework is 2.5 megabytes, with 36
- dependencies. This isn't bad for a big web application, but I write a lot of
- tiny web applications where megabytes of dependencies just feels wrong. As a
- result, I have in the past often just used the http module directly. This
- framework is a nice middle ground; it provides some of the utility of big web
- frameworks, but without adding a ton of extra dependencies to the application.
-
- ## Documentation
-
- ### webframe.App([options])
-
- Creates a new instance, with an optional options argument.
-
- Options:
-
- * `server`: Your own HTTP (like the one created by http.createHttpServer).
- * `listen`: Whether to call the `listen` method on the server. Defaults to
- true.
- * `port`: The port to listen on. Defaults to the PORT environment variable, or
- 8080.
- * `host`: The host to listen on. Defaults to the HOSTNAME environment variable,
- or "127.0.0.1". For the server to be accessible to the outside world, listen
- on "0.0.0.0".
- * `client_utils`: Whether to add some utility functions to /webframe.js.
- Defaults to false.
- * `res404`: The string to return for a 404 error. "{{pathname}}" will be
- replaced with the pathname.
- * `res403`: The string to return for a 403 error. "{{pathname}}" will be
- replaced with the pathname.
-
- ``` JavaScript
- var app = new webframe.App({ client_utils: true });
- ```
-
- ### app.route(method, path [, middleware], func)
-
- Add a route.
-
- * `method`: What HTTP method the route should be available at.
- Valid options: "GET", "POST", "PUT", "DELETE", or "ALL".
- * `path`: The path. If it starts with a "^", it will be interpreted as a
- regular expression (with `new RegExp(path)`), and the route will be ran on
- all matching paths. Routes without a pattern are prioritized over those with
- a pattern.
- * `middleware`: Optional. An array of middleware functions which will be ran
- before the route's function.
- * `func`: function(request, response). The function which handles the request.
-
- ### app.get, app.post, app.put, app.delete, app.all
-
- Utility functions which just call app.route() with a predefined method value.
-
- E.g `app.get("/foo", handler)` is the same as
- `app.route("GET", "/foo", handler)`.
-
- ### app.info(str), app.notice(str), app.warning(str), app.panic(str)
-
- Logging functions. They all print a message. `app.panic` also exits, and is
- intended for errors so bad you have to crash.
-
- In the future, it will be possible to control the logging level.
-
- ### Middleware
-
- `webframe.middleware` contains middleware for the route functions.
-
- * `webframe.middleware.cookies`: Adds `request.cookies`, parsed COOKIE header.
- * `webframe.middleware.params`: Adds `request.params`, parsed URL parameters.
- * `webframe.middleware.payload`: Adds `request.payload`, a string (max 50
- kilobytes) of the request payload.
-
- In the future, there will be middleware for form data over POST too.
-
- ### Modifications to the request and response objects
-
- * `req.urlobj`: The result of `url.parse(req.url)`.
- * `res.json(object)`: A utility function to respond with JSON.
-
- ### webframe.static(root[, before])
-
- Serve static files.
-
- * `app.get("^.*", webframe.static("web"))` will serve all the files in the
- `web` directory, so `/index.html` will serve `web/index.html`.
- * `app.get("^/static/.*", webframe.static("web", "/static"))` will serve all
- files in the `web` directory under `/static`, so `/static/script.js` will
- serve `web/script.js`.
-
- ### Transformations - app.transform(extension, mime, func)
-
- Webframe has a way to transform files of one file type to an other, for example
- transforming typescript into javascript, or sass into CSS.
-
- * `extension`: The file extension to transform.
- * `mime`: The result mime type.
- * `func`: function(path, writeStream). The transform function.
- * `writeStream.headersSent`: Whether headers have been sent or not.
- * `writeStream.status`: The status code. Default: 200 (or 500 for errors)
- * `writeStream.headers`: An object containing the headers to be sent.
- Default: `{ "content-type": <mime> }`
- * `writeStream.write`: function(data). Write response data.
- * `writeStream.end`: function([data]). End the request, optionally with
- response data.
- * `writeStream.error`: function(err). Log an error, respond with status
- code 500 (or the content of `writeStream.status` if it's not 200).
-
- Example (assumes you have the node-sass module installed):
-
- ```
- var sass = require("node-sass");
-
- app.transform(".sass", "text/css", (path, writeStream) => {
- try {
- var str = fs.readFileSync(path, "utf8");
- } catch (err) {
- writeStream.status = 404;
- return writeStream.error(err);
- }
-
- try {
- var result = sass.renderSync({ data: str });
- writeStream.end(result.css);
- } catch (err) {
- writeStream.error(err);
- }
- });
- ```
-
- Now, any .sass file served with `webframe.static` will be compiled into CSS,
- and sent with the browser with the MIME type "text/css". The result is also
- cached, so the expensive sass compilation will only happen the first time the
- file is requested, or when the file changes. The result will not be cached
- if you call writeStream.error.
|