wk

wk is a CLI tool for developing single-page-applications with web components syntax.

Introduction

wk is a simple and opinionated CLI tool that imposes a simple approach that (only) uses html, css and javascript for writing web applications.

This CLI has 3 simple commands that is sufficient to

• Initialize a project and create necessary boilerplate files
• Start a development file server and a file watcher that auto-builds the source code as you change
• Minify & merge the css and javascript source code for production

Installation

This CLI tool is available as an executable binary only for linux-x86-64

wget wk.js.org/dist/wk

Goals

• Small javascript output (~50kb for reasonably large web apps)
• Fast development (<5ms) and production (<2s) builds
• Zero configuration and external tools (other than wk) for development
• No new languages/markup to learn other than HTML/CSS/JS

Who is this for?

This is an experimental build tool that I use in my own projects, and I don't expect anyone to find this useful and use in their own work.

I have prepared this document for those who really dislikes modern web development and looking for an alternative approach to build web applications.

Since I am biased against modern methods of web development, I tried to get rid of all unnecessary (IMO) frameworks, transpilers, task runners, dependency managers as much as possible and implemented some of their functionality in this CLI in a very minimal way.

Here are the list of the most radical decisions in this web application development method that can show you if this CLI is a good fit for you or not.

1. Imperative over Declarative / Markup and logic separated

Despite writing more code, imperative programming is (IMO) easier to debug and has less hidden behaviour. Not having the full control on rendering makes trivial problems like 'preventing redundant re-renders' a big issue and forces you to either learn the internals of the declarative rendering logic or blindly follow the constantly-changing-best-practice for that specific problem.

Wk also tries to keep markup and logic separated which is impossible for declerative UI programming. Mixing markup and logic requires you to invent a new language or a new syntax (eg: directives in angular/vue and jsx in react). HTML/JS/CSS are already very high level and powerful concepts and adding another language to the web is redundant. There is no need to learn a new programming or markup language since current ones already sufficient to build complex web applications. Since wk does not introduce any runtime itself, only concept that should be understood is the lifecycle callbacks of the standart web components.

2. Manual DOM manipulation

Methods like data binding, virtual DOM are not used in projects developed with wk. Those concepts introduces lots of complexity and mostly ends up writing more code than their manual DOM management counterparts. Hence all dom manipulation is done manually with using methods and properties like querySelector, cloneNode and , innerHTML. In order to develop web apps with this tool you must be proficient with standart Web APIs and manual DOM manipulation techniques. Wk is not a beginner friendly tool and it expects you to know all Web APIs by heart.

3. No 3rd party tool support and not configurable

Wk is especially designed as non-integrable with other popular tools like webpack, grunt, gulp, babel, typescript, sass, eslint, package.json and etc.. If one of these tools are essential for your workflow or if you like configuration files wk is probably not a good tool for you.

CLI Usage

Initializing a project

wk init

• Creates boilerplate folders/files for a project if not initialized before

Starting development server

wk start

• Starts the file server that hosts the web application on 127.0.0.1 in an available port
• Starts a file watcher that concatanates the source files (css, js, html) upon change

Making a production build

wk build

• Clones ./public folder as ./build
• Minifies & merges all javascript and css code under ./src folder and puts them into ./build folder with a time seed

Documentation

documentation is not complete

A freshly initialized project will have following 5 files

./src/components/web-app/web-app.html
./src/components/web-app/web-app.css
./src/components/web-app/web-app.js
./public/index.html
./jsconfig.json

• every folder put into components folder counts as one component and every component folder must have one js,css and html file in it.So web-app.js, web-app.css and web-app.html are necessary for the web-app component

• web-app component is the prime component of a wk project and entry point for the program is the first line of web-app.js

• you can create a new component by creating the folder and necessary 3 files or you can just use wk new component-name command

• with wk start command, these these js, css and html files are merged and served via an http server built into CLI tool

dont serve the base project folder or public folder yourself for development always use wk start command for development

• main document of the web application is ./public/index.html, you can include 3rd party scripts/css in it

• all assets and 3rd party js/css files should be stored in ./public folder

• if you would like to make a production build use wk build command, it will copy all your assets in ./public folder and minify all your source code into a new folder ./build. you can move content of this build folder to any http file server to serve your application

Style Guide

projects written with wk are encouraged to use following style guide

• variables and functions are snake_case
• constants are UPPER_SNAKE_CASE
• brace placement is in Allman Style
• operators are surrounded by one space
• global variables start with g_ prefix
• indentation is done with tabs
• there is a soft limit on 3 level indentation and 80 char column size

Changelog

wk is in under active development since 2018 and i have made lots of breaking changes to it, below is the track of all those changes

unfortunately there is no foreseeable date for stable version release yet

Migration Notes 0.4.14 to 0.5.0

July-20-2020

• standart web components syntax is adopted for components.
• main component renamed from app to web-app (to match web components naming)

Migration Notes 0.3.0 to 0.3.1

August-26-2019

folder structure is changed with this release (this is a breaking change)

• www is changed to public since this folder is for serving static files, i thought it would be a good idea to name it www/, (just like default apache root folder name) but no one get the reference and i decided to change its name to public/ which is inspired from create-react-app

• src is kept same src is a good abbrevetion for name 'source' so i kept it as it is

• com is moved under src and renamed as src/components

folder name 'com' has an undesired resemblance with Android package names ( eg: com.foo.bar ) i thought having 3 letter base folder names looked cool ( www, src, com) but every developer that tried to use wk, complained with these cryptic namings.

Migration Notes 0.2.22 to 0.3.0

August-18-2019

i have decided to make a breaking change to wk and dropped typescript support

even though i love typescript and typed languages for programming, i had some negative experiences with 'typescript' so far

• typescript transpiler is slow and getting slower with each release. i have tried lots of things but there is no way for me to solve this problem (i have even experimented alternative compiler 'sucrase')
• typescript language is growing very rapidly and wk uses outdated typescript features like triple-slash-reference-directives and namespace keyword.wk already encourages to use a small subset of typescript language, the statement 'wk is a toolkit for developing web apps with typescript' is getting less true with each typescript release (which is too frequent for my taste)
• even it is very easy to understand how it works, typescript is complexifying wk for new learners, new wk users are always asking typescript related questions instead of wk architecture to understand a project written with wk
• as of aug 2019, es6 'class' and 'extends' keyword is very well supported by major browsers, which makes one of the transpilation reasons fade away
• one less dependency in the project always feels good

what is gained by dropping typescript

• faster build times (5-10 seconds to 10-50 milliseconds)
• less things to learn
• smaller codebase for maintaining wk development itself

what is lost by dropping typescript

• type checks, IDE refactoring features

still, i am not convinced that dropping typescript is a good idea, since wk is still in an experimental stage, i may re-introduce typescript in the future