Knuckles

Appearance

Migrating from knockout-lint ​

WARNING

Knuckles has taken knockout-lint's place which is no longer maintained.

Welcome to Knuckles 🥳👊 We're glad to see you here!

A bunch of development tools made for Knockout by @tscpp, including knockout-lint, have been brought together to form the Knuckles toolkit! You can still choose to use each tool individually 😉

This guide will help you migrate your project to using Knuckles analyzer.

Improvements ​

  • Performance: The new underlaying transpiler that converts views to TypeScript snapshots (code) have been improved and is significantly faster.
  • Stabillity: Stabillity of the tools have been improved by fixing bugs and refactoring code. Overall, the toolkit is much more stable than before and should be easier to use.
  • Additions: Many new features have been introduced, including using external tools (such as TypeScript and ESLint) in bindings and optional/dynamic strictness for type-checking.

Breaking Changes ​

Breaking changes include, but is not limited to:

  • New minimum requirement of Node.JS version >=18.
  • Packages are converted to ES modules, but can still be used in CommonJS projects.
  • New syntax (see below).

Installation ​

sh
# Make sure you have the CLI installed.
$ npm install --save-dev @knuckles/cli

# This will configure the analyzer and typescript for you.
$ npx ko add typescript
sh
# Make sure you have the CLI installed.
$ yarn add --dev @knuckles/cli

# This will configure the analyzer and typescript for you.
$ yarn ko add typescript
sh
# Make sure you have the CLI installed.
$ pnpm add --save-dev @knuckles/cli

# This will configure the analyzer and typescript for you.
$ pnpm ko add typescript
sh
# Make sure you have the CLI installed.
$ bun add --save-dev @knuckles/cli

# This will configure the analyzer and typescript for you.
$ bun ko add typescript

See the 'getting started' guide and analyzer overview.

Syntax ​

The syntax used by Knockout itself has not been changed (obviously), but the syntax used by the analyzer (previously linter) has.

Linking View Models ​

Linking view models is now done through hints. Hints always start with "ok" (instead of "ko"). Hints provide various insights about the view, and the "with" directive provides the data for the descendant context.

See the full view hint reference for more details.

html
<!-- ko-import ViewModel from './viewmodel.js' -->
<!-- ko-viewmodel ViewModel -->
<!-- ok with: default from './viewmodel.js' -->
  ...
<!-- /ok -->

Defining Binding Handlers ​

Binding handlers are now defined globally, in the ko.bindingHandlers namespace. Since the binding handlers are defined globally (in a non-determenistic way), the binding handlers must also be defined globally.

Q: So how do I limit which views can access what binding handlers?

You have to limit what binding handlers are globally defined in certain parts of your project. This can be done by not including declaration files that declare binding handlers that doesn't exist in the tsconfig used by the analyzer (which can be configured). Ask if you have questions.

This is how you would define a binding transform globally. After this is defined globally, the view can automatically use the binding handler.

ts
import { KnucklesIdentityBindingTransform } from "@knuckles/typescript/types";

declare global {
  interface KnucklesBindingTransforms {
    i18n: KnucklesIdentityBindingTransform<string>; 
  }
}

What's next? ​

If you have any questions, feel free to start a discussion.