Knockout 3 to 4 Guide

Knockout 3.x to TKO

This guide is for teams that already have a Knockout 3.x codebase and want a practical path onto the TKO packages.

TKO keeps the familiar Knockout programming model, but changes the packaging, build structure, and some binding-expression behavior. For most migrations, start with @tko/build.knockout; use @tko/build.reference when you want to assemble a more modular setup or follow the TSX / ko-* examples used elsewhere in this docs set.

Start with the right package

• @tko/build.knockout Recommended for most migrations. It is the compatibility-focused build and the closest match for a traditional Knockout application.
• @tko/build.reference Better for custom or modular setups where you want to compose providers and features more explicitly, and the build used by the TSX / ko-* docs path.

The biggest changes

Packaging changed

Classic Knockout shipped as a single distribution. TKO is published as scoped npm packages, with the main entry points being @tko/build.knockout and @tko/build.reference.

Browser expectations changed

TKO targets modern browser environments and stricter CSP defaults. If your app still depends on specific older browser behavior, validate it against the exact build you plan to ship before migrating.

Binding expressions are stricter

The binding parser is designed to work without eval or new Function, which is a security and CSP improvement. The compatibility build still rewrites a few legacy inline function (...) { ... } binding expressions, but if you are moving to the reference build or cleaning up code, prefer named methods or arrow functions.

<!-- Avoid -->
<button data-bind="click: function () { count(count() + 1) }">Add</button>

<!-- Prefer -->
<button data-bind="click: () => count(count() + 1)">Add</button>

or move the logic onto the view model and bind to the named method:

<button data-bind="click: increment">Add</button>

Security and CSP improve

TKO is designed for stricter Content Security Policies and avoids the older eval-style parsing approach. If your application needs stronger CSP compliance, this is one of the clearest migration benefits.

Async startup

ko.applyBindings returns a Promise. If you chain bootstrap work after binding or need to wait for async bindings to finish, account for that in your startup flow.

What is still familiar

• ko.observable, ko.observableArray, and ko.computed
• The standard binding model with data-bind
• Custom bindings and components
• The overall MVVM-style structure of a Knockout application

Migration checklist

1. Start with @tko/build.knockout unless you have a reason to compose a custom build.
2. Start from the latest 4.x stable release, and record the exact package version you validate during migration.
3. Search your templates for inline function (...) { ... } expressions in data-bind attributes and replace them where you are moving toward the reference build or want cleaner modern code.
4. Re-test browser support assumptions against your actual target matrix.
5. Re-test custom bindings, component loaders, and any advanced parsing or provider integrations.
6. Migrate one page or feature slice at a time instead of swapping the whole runtime at once.

Feature comparison

Capability	Knockout 3.x	@tko/build.knockout	@tko/build.reference
Classic observables and bindings	Yes	Yes	Yes
Compatibility-focused migration target	Baseline	Yes	Partial
Modular build composition	Limited	Some	Yes
CSP-friendly binding parser	No	Yes	Yes
Legacy compatibility workarounds	More common	Reduced	Reduced

When not to migrate yet

• Your templates rely heavily on legacy inline binding expressions you cannot easily change.
• Your application depends on old plugins that assume Knockout 3 internals and have not been validated against TKO.
• Your app still depends on browser-specific behavior you have not validated against the TKO build you plan to use.

Where to look next

• Introduction for the current package story.
• Bindings, Observables, and Components for the APIs you will touch most during a migration.