diff --git a/README.md b/README.md index 469e8f92..bf919c60 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@ -### TKO (“Technical Knockout”) +# TKO (“Technical Knockout”) [![npm version](https://badge.fury.io/js/tko.svg)](https://badge.fury.io/js/tko) [![Join the chat at https://gitter.im/knockout/tko](https://badges.gitter.im/knockout/tko.svg)](https://gitter.im/knockout/tko?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) @@ -11,72 +11,135 @@ -**TKO** houses the monorepo of [Knockout](https://github.com/knockout/knockout). - - -### Getting Started - +1. [Intro](#intro) +2. [Getting Started](#getting-started) + 1. [Download](#download) + 1. [Reference](#download-reference) + 2. [Compatibility build](#download-compatibility) + 3. [Over CDN](#download-cdn) + 2. [Usage / import](#usage) + 1. [ESM](#imports-esm) + 2. [IIFE](#imports-iife) + 3. [CommonJS](#imports-cjs) + 4. [MJS](#imports-mjs) + 3. [Sites](#sites) +3. [Using the Monporepo](#monorepo) + 1. [Test suit](#tests) +4. [Objectives](#objectives) +5. [Roadmap](#roadmap) +6. [License](#license) +7. [Shoutouts](#shoutouts) + + +## Getting Started + + + +**TKO** serves as a foundation for `Knockout 4` which goal is to become a drop-in replacement and a feature-rich expansion of already existing KnockoutJS (3+) while adhering new standards and paradigms of web developmentent. Its built on top of current KnockoutJS featurelist while being [mostly compatible](https://www.tko.io/3to4) with it, further about it and build differences at [download](#download) section. + + +### Download To install use one of the usual package managers e.g. +#### Reference build: - $ `yarn add @tko/build.reference` - $ `npm install @tko/build.reference` +This is the canonical build without compatibilities with older KnockoutJS versions -Over CDN +#### Compabibility build: +- $ `yarn add @tko/build.knockout` +- $ `npm install @tko/build.knockout` +This Knockout build has some backwards compatibility that is not in the reference build. See the build differences, here: https://tko.io/3to4 -- Reference Build: https://cdn.jsdelivr.net/npm/@tko/build.reference@4.0.0-alpha8/dist/build.reference.min.js +#### Over CDN +> **Note**: Latest version available is `alpha8` -#### Knockout Build -The Knockout build has some backwards compatibility that is not in the reference build. See the build differences, here: https://tko.io/3to4 +- *Reference* Build: https://cdn.jsdelivr.net/npm/@tko/build.reference@4.0.0-alpha8/dist/build.reference.min.js +- *Compatibility* Build: https://cdn.jsdelivr.net/npm/@tko/build.knockout@4.0.0-alpha8/dist/build.knockout.min.js -It's available as `@tko/build.knockout`, and over CDN: -- Knockout Build https://cdn.jsdelivr.net/npm/@tko/build.knockout@4.0.0-alpha8/dist/build.knockout.min.js +### Using TKO in a project +Currently there is no default package root import due to availability of different builds listed below. Every TKO build supports all listed below module types: +* ESM -### Using the Monorepo + ```js + import ko from "@tko/build.reference/dist/index.js" + ``` -| Command | Effect | -| ------- | ------ | -| $ `git clone git@github.com:knockout/tko` | Clone the repository. -| $ `npm install -g yarn` otherwise | Ensure yarn is globally available -| $ `yarn` | Install local node packages and link tko modules -| $ `yarn test` | Run all tests. See below. -| $ `yarn watch` | Run all tests and watch for changes. See below. -| $ `yarn build` | Build tko\[.module\]\[.es6\]\[.min\].js files, where `.es6` version has not been transpiled -| $ `lerna publish` | Bump versions and publish to npm registry + `ko` is default export so feel free to change import name on your desired. -Checkout `package.json => scripts` for more commands that can be executed with `yarn {command}`. +* IIFE -In each individual `packages/*/` directory, you can also run (presuming `rollup` and `karma` are installed globally): + ```js + import "@tko/build.reference/dist/browser.js" + // or use already minified bundle + import "@tko/build.reference/dist/browser.min.js" + ``` -| Command | Effect | -| --- | --- | -| $ `karma COMMAND ../../karma.conf.js [--once]` | Test the local package, where COMMAND is e.g. `start` or `run` -| $ `rollup -c ../../rollup.config.js` | Build the package into the local `dist/` + Imported namespace is available *only* as `tko`. + +* CommonJS + + ```js + const ko = require("@tko/build.reference/dist/index.cjs") + ``` + +* MJS + + ```js + import ko from "@tko/build.reference/dist/index.mjs" + ``` + + `ko` is default export so feel free to change import name on your desired. +> **Note**: you can check imported TKO version by looking at its namespace attribute `.version` in runtime. -#### Testing with `yarn test` and `yarn watch` -The `yarn test` and `yarn watch` commands can be used in the root directory, where it will run across all tests, or alternatively in any `packages/*/` directory to run tests -specific to that package. +### Sites -Optional arguments to `yarn test` include: +Currently there are 2 points of interest which further would be considered a wiki: +- https://tko.io - wiki specifically for TKO (*not Knockout 4*) +- https://brianmhunt.github.io/knockout - Work In Profress wiki/docs for Knockout + + +## Using the Monorepo + +The default package manager for monorepo currently is `npm` with the addition of [Lerna](https://lerna.js.org/docs/getting-started) as a viable choice for monorepo management. + +First thing at getting familiar with the project monorepo is to look at `./Makefile` at project root. Since its a separate file spanning entire repo, we will cover only the most commonly used commands: + +| Command | Effect | +| ------- | ------ | +| $ `git clone git@github.com:knockout/tko` | Clone the repository. +| $ `make` | Install all dependencies, build *reference* and *compatibility* versions of TKO at `builds/*/dist/*` without any transpilation. It is the `default` makefile behavior calling `all` directive. +| $ `make clean` | empties build directories `.../dist/*` and `package-lock.json`'s inside of every `package/*` and `builds/*` +| $ `npm i` | Install local node packages and link tko modules +| $ `make test` | Run all tests. See below. +| $ `make publish-unpublished` | Bump versions and publish to npm registry + +In each individual `packages/*/` directory, you can also run (presuming `esbuild` and `karma` are installed globally): + +| Command | Effect | +| --- | --- | +| $ `make test` | Test the local package, abstraction of `npx karma start ../../tools/karma.conf --once` +| $ `make` | Build the package into the local `dist/` -- `--sauce` — use Sauce Labs to test a variety of platforms; requires an account at Sauce Labs and `SAUCE_USERNAME` and `SAUCE_ACCESS_KEY` to be set in the environment. -- `--noStartConnect` — Do not start a new Sauce Connect proxy instance for every -test; requires that Sauce Connect be already running. +### Test suit -#### `visual.html` +```sh +make test +``` -Note that running `karma` or `rollup` will create a `visual.html` file that shows the proportional size of imports into each package. +Testing suit is build around Karma and Jasmine. The `make test` command can be used in the root directory, where it will run across all tests, or alternatively in any `packages/*/` directory to run tests specific to that package from their respective `spec` folders. -### Objectives +## Objectives TKO aims to become a base for future versions of Knockout. The objectives include: -- Modularization into ES6 and separate projects, with compilation using an ES6 compiler like [Rollup](http://rollupjs.org/). This solves several problems with Knockout, including: +- Modularization into ES6 and separate projects, with compilation using an ES6 compiler like [esbuild](https://esbuild.github.io/). This solves several problems with Knockout, including: - Some folks want to roll-their-own with e.g. removing components - Compilation is now with Closure compiler, which is actually transliterating – meaning the *debug* and *minified* versions have different code paths (mostly in the form of things exposed in *debug* being missing in the *minified* version) - The compilation of Knockout is just concatenation, leading to difficulties with maintainance, severance, and replacement @@ -89,16 +152,16 @@ TKO aims to become a base for future versions of Knockout. The objectives inclu - Quality plugins have lots of boilerplate for compilation, release, documentation, and testing -## Next steps +## Roadmap / Next steps There's an [issue for that](https://github.com/knockout/tko/issues/1). -## License +## License MIT license - [http://www.opensource.org/licenses/mit-license.php.](http://www.opensource.org/licenses/mit-license.php) -## Shout Outs +## Shout Outs