Creating ESP Applications

To start a new ESP web application or web site, first create a new directory named for the application, then run esp init.

$ mkdir demo $ cd demo $ esp init

This will prepare your application to run ESP by generating two configuration files and creating a dist directory to hold your rendered application.

You can now create web pages to be served by ESP. Create a test ESP page under the dist directory called dist/index.esp with the contents:

<html> <body> <h1>Hello World</h1> </body> </html>

If a directory named dist is not present, esp will serve web content from the current directory. It is more secure to have only the public web documents being visible in a dist directory.


To run your application, run esp serve to serve browser requests.

$ esp serve

You can also just run a plain esp command without arguments. It is the same as esp serve.

$ esp

You can now browse to http://localhost:4000/index.esp to see the new page. The first time, there will be a brief pause as the page is compiled and saved in the cache directory. Next time, the page will be served from memory. If you modify the page, it will be transparently re-compiled. If you restart esp the cached module will be loaded and the page will not be re-compiled.


There is another way to create ESP applications and that is by installing ESP skeletons. Skeletons are integrated starter packages for ESP applications. Skeletons typically include default web pages, layouts, partial pages, stylesheets, scripts and required dependent packages for an easy, one-step launch of your web application.

Installing skeletons is easy via the Pak utility. For example, to install esp-html-skeleton.

$ pak install embedthis/esp-html-skeleton [Install] exp-js 0.3.2 [Install] exp-less 0.3.0 [Install] exp-css 0.3.1 [Install] exp-esp 0.3.1 [Install] exp-html 0.2.0 [Install] exp-canon 0.3.0 [Install] esp-mvc 5.5.2 [Install] esp-html-skeleton 5.5.1

This installs the esp-html-skeleton and all dependent packages. The skeleton includes:

Files with a .html.exp extension are files that may contain server-side Javascript that Expansive will run at development render-time. To render and server pages, run expansive.

$ expansive

Read more about skeletons in Application Skeletons.

Configuration Files

The three configuration files esp.json, pak.json and expansive.json play a central role in configuring and managing the evolution of your application. Read more about these files in Configuring ESP.


The esp init and pak commands will make directories when creating an application or installing packages and generating components.

Directory Purpose
cache Cached shared libraries for compiled controllers and pages
contents Input web content source directory used by Expansive when rendering into the dist directory.
dist Directory of web content to serve to browser clients. Files outside the dist directory are not visible to the client. If a dist directory does not exist, files in the current directory will be served.
dist/images Client side assets: images and media
dist/css Client side CSS
dist/lib Rendered library content originally sourced from installed packages.
controllers ESP controller C source code
db Databases and database migrations
layouts Layout template pages used by Expansive. Layouts provide the master page look and feel. Layout pages provide the outer HTML that wraps individual content pages.
lib Library content for installed packages. These files are copied from the paks directory for scripts, stylesheets, fonts and resources that should be rendered to the dist directory.
migrations Database migration scripts
paks Installed packages. This is the location of the package's raw content. Required files are exported into the lib directory and ultimately into the dist directory when the site is rendered by Expansive.
partials Partial ESP pages used by Expansive. These pages may be included by content or layout pages.
src Other application C source code

© Embedthis Software. All rights reserved.