Quick Start

Run this in your terminal:

~$ sudo npm install -g stark
~$ stark new yoursite
~$ cd yoursite/
~/yoursite$ stark watch-server

Then open the printed link in your browser (usually it's http://localhost:7780). You should see a page like this:

Overview

Lets take the typical web development process:

A sketch is created for some idea. A designer may transform this into PSD's for the app/site. Development starts by splitting the design into HTML, CSS and JavaScript layers which are further developed as three separate, but very inter-connected subprojects.

Stark changes this process: you build the app or site out of small components that encapsulate HTML/template, CSS and JavaScript parts. The components depend on each other. Stark does the rest.

Building a web project this way reduces complexity: the number of interconnected layers / dependency trees a developer has to keep in mind. The components (although consisting of parts in different languages) have very high cohesion and reduce coupling. They visually map to what one sees on the screen in the final result.

You may notice that the idea is very similar to Web Components. However there are some differences:

• you don't have to wait for browser support,
• expressive syntax,
• more goodies built into Stark (YAML parts, development server, React support, etc.)

How Multi-Part Components work

• Stark treats multiple files with the same basename but different extensions as parts of the same component.
• There is also a special file format (*.mpc) for having all parts in the same file.
• You can freely combine *.mpc and other files.

MPC file contents look like this:

--- html ---
 
<!-- Note: empty lines between part content and header are mandatory. -->
 
--- css ---
 
/* You can add as many minuses at the end of header as you like: */
 
--- js --------------------------------------------------------
 
/// Tip: use comments to further structure your code. ---------

Components can depend on each other. This is expressed in their requirement part:

--- requirements ---
 
jquery/dist/jquery
Widget2:    ./widget2

Stark builds a single dependency graph from these requirements (starting from index.mpc file) and generates HTML, CSS, JavaScript files for your app or site.

---

Reference

Commands

You can get a full documentation of command line options by running stark without options or stark -h.

The general structure is: stark COMMAND [OPTIONS].

Commands:

I recommend using stark watch-server for development and stark build for automated builds.

Directories

Now lets look through the contents of your site directory:

build/

You will find the compiled pages, scripts, styles and other files here. Directory contents should look like this:

Component directories: lib, bower_components, node_modules

These directories are added to include path. Stark will search for requirements in these directories.

You should put your own templates, widgets, JS modules into lib. You should try installing third party libraries with bower and npm when available.

pages/

Directory for your page components. pages/yourpage.mpc will be used to generate build/yourpage/index.html .

static/

The contents of this directory are recursively copied to build/static/.

Files

config.mpc

The data from the yaml part of this file will be available as site.config value in templates.

Alternatively you can rename the file to config.yaml. (Don't forget to remove the MPC part headers).

index.mpc

This is the main page of the site and the starting point for CSS and JavaScript generation:

• Stark creates build/index.html from template parts of this page.
• Stark creates build/static/script.js and build/static/style.css from the requirements of this page.

build/index.html

Stark will compile this HTML file from the template parts of index.mpc.

build/static/script.js

Stark will compile JavaScript from index.mpc dependencies into this file.

build/static/style.css

Stark will compile CSS from index.mpc dependencies into this file.

Component Parts

Stark pages and components are made of parts. Some of them are processed before including in the final output, others are copied verbatim.

---

Other

Contributing

• Please use Github Issues for bug reporting and feature requests.

• Please keep your pull requests small and make sure they merge easily with the master branch before submitting.

• Please send any other feedback to my email: emilis.d@gmail.com. It is most welcome.