<commit_before>@page migrate-3 Migrating to CanJS 3
@parent guides/commitment 2
@templateRender <% %>
@description This guide walks you through the step-by-step process to upgrade a 2.x app to CanJS 3.
@outline 0

@body

CanJS 3 introduces an even more modular project structure and several new features, while having a minimal number of deprecations and removals from the [2.3 API](//v2.canjs.com/docs/).

This guide goes over:

* [*Pre-migration preparation*](#Pre_migrationpreparation) you can do in your current 2.x project to more easily move to 3.x in the future.
* [The *minimal migration path*](#Minimalmigrationpath), which includes the fewest changes required to upgrade from 2.x to 3.x.
* [The *modernized migration path*](#Modernizedmigrationpath), which includes upgrading your code to match more modern conventions (such as using the new npm packages).
* [The *latest & greatest migration path*](#Latest_greatestmigrationpath), which uses all of the modern libraries we are most excited about (such as [can-define]).
* [How to *avoid future deprecations & removals*](#Avoidfuturedeprecations_removals) in releases after 3.x

## Pre-migration preparation

Before upgrading your project from 2.x to 3.x, make sure your project builds successfully and all the tests pass.

Additionally, you can take the following steps in your CanJS 2.x app to prepare it for migrating to CanJS 3.

### Use the module folders

You can start importing CanJS code in a modular way before moving to CanJS 3.

For example, you might be using [can-component] like this:

```js
var can = require("can");

can.Component.extend({ ... });
```

Update your code to instead look like this:

```js
var Component = require("can/component/component");

Component.extend({ ... });
```

Use the same pattern for the other modules you are using.

Here’s a list of all the `can.` properties in CanJS 2.3 that can be replaced with modular paths:

- `can.autorender` — `can/view/autorender/autorender`
- `can.bindings` — `can/view/bindings/bindings`
- `can.Component` — `can/component/component`
- `can.compute` — `can/compute/compute`
- `can.Construct` — `can/construct/construct`
- `can.Control` — `can/control/control`
- `can.Deferred` — `can/util/deferred`
- `can.define` — `can/map/define`
- `can.ejs` — `can/view/ejs/ejs`
- `can.event` — `can/event/event`
- `can.fixture` — `can/util/fixture`
- `can.LazyMap` — `can/map/lazy/lazy`
- `can.List` — `can/list/list`
- `can.Map` — `can/map/map`
- `can.Model` — `can/model/model`
- `can.Model.Cached` — `can/model/cached/cached`
- `can.mustache` — `can/view/mustache/mustache`
- `can.Object` — `can/util/object/object`
- `can.route` — `can/route/route`
- `can.stache` — `can/view/stache/stache`
- `can.util` — `can/util/util`
- `can.view.callbacks` — `can/view/callbacks/callbacks`

### Replace uses of `can.$`

[`can.$`](//v2.canjs.com/docs/can.$.html) allows you to access the underlying DOM library bundled with CanJS; for example, jQuery in `can.jquery.js`.

You might be using it in your code to easily reference the library:

```js
var can = require("can");
var body = can.$('body');
```

Update your code to explicitly require the library on which you depend. For example:

```js
var $ = require("jquery");
var body = $('body');
```

### Set `leakScope` on components

CanJS 2.2 introduced [can-component.prototype.leakScope leakScope: false] as a property on a [can-component]. This prevents values in parent templates from leaking into your component’s template. In CanJS 3, **leakScope** is now `false` by default.

If you have a template like:

```
<some-component></some-component>
```

That you render with a [can-map map] containing a `page` property like so:

```js
render(new Map({
	page: "home"
}));
```

This `page` property is not available within `some-component`’s own template.

If the component’s template looks like:

```
<h1>Hello {{page}}</h1>
```

It can only lookup the `page` property on `some-component`’s own [can-component.prototype.ViewModel]. To restore the behavior in 2.x, simply set [can-component.prototype.leakScope] to be `true` on the component:

```js
Component.extend({
	tag: "some-component",
	ViewModel: ...,
	leakScope: true
});
```
@highlight 4

## Minimal migration path

If you are already using `can` through npm, simply run the following command to install the latest version:

```
npm install can --save
```

This will update your `package.json` to look something like this:

```js
{
  ...
  "dependencies": {
    "can": "^<%canjs.package.version%>"
  }
}
```

The `^` ensures you get minor and patch releases as those are released.

At a minimum, to upgrade your code for CanJS 3, you must make all of the following changes to your code:

### Use `can/legacy`

In your code where you normally would import `can`, instead import `can/legacy`:

```js
var can = require("can/legacy");
```

This will give you a `can` object with *most* of the same APIs as in 2.3, with a few exceptions:

* [can.mustache](v2.canjs.com/docs/can.mustache.html) is not included with `can/legacy`, but it can still be installed as a [separate package](https://www.npmjs.com/package/can-mustache).
* The former `can.view` functionality no longer exists; see below for more details.

### Asynchronous `inserted` & `removed` events

In your [can-component]s, the [can-util/dom/events/inserted/inserted inserted] and [can-util/dom/events/removed/removed] events were previously fired synchronously as the element was inserted or removed from the DOM. To improve performance, these events are now fired asynchronously.

There is now a [can-component/beforeremove] event that fires synchronously in case you need to perform memory cleanup. For example, you might need to access the parent’s viewModel:

```js
Component.extend({
	tag: "my-panel",

	events: {
		"beforeremove": function(){
			canViewModel(this.element.parentNode).removePanel(this.viewModel);
		}
	}
}
```

### Replace uses of `can.view`

The `can.view` methods have been removed in CanJS 3. The most common use was to create a template renderer from a script element within the page.

Instead of:

```js
var render = can.view('some-id');
```

Just use the DOM APIs and pass the string directly into [can-stache]:

```js
var templateString = document.getElementById('some-id').innerHTML;
var render = stache(templateString);
```

If you were using `can.view.preload` then use [can-stache.registerPartial] instead.

```js
stache.registerPartial("some-id", renderer);
```

### Use native Promises

Native [Promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) are used instead of jQuery promises which means you need to:

* Include a Promise polyfill if targeting browsers that do not have native support. [Steal](http://stealjs.com/) includes a polyfill for you.
* Use `.catch()` instead of `.fail()`.
* Use `.then()` instead of `.done()`.

Note that only a single value is returned from a native Promise.

### Passing the `this` value to a helper

[can-stache] now passes a [can-compute] to [can-stache.Helpers helpers].

If you were passing the `this` value to a helper like so:

```
{{helper .}}
```

You can fix this either by having your helpers handle computes, or by using [can-stache/expressions/call call expressions] instead:

```
{{helper(.)}}
```

### No more global scope names

Most recently-built applications do not depend on adding to the global namespace, but in case you have code that does:

```js
Construct.extend("foo.bar", ...)
```

Which sets `window.foo.bar`, this argument is no longer accepted by [can-construct]. If you *really* need to set a global, you can do so yourself using the return value of [can-construct.extend].

Instead, the first argument to [can-construct.extend] is the name of the constructor function. This is nice for development as you’ll get named objects in your dev tools.

### Using `steal-stache` for templates

If you use StealJS, you’ll need to install [steal-stache] to load your templates:

```
npm install steal-stache --save
```

You don’t need to do anything else to make your templates load correctly.

## Modernized migration path

CanJS 3 is divided into separate npm packages. This allows us to more quickly update parts of CanJS without affecting other functionality.

In addition to the above, take advantage of the individual packages by installing and using them directly to set your project up for easier upgrades in the future.

For example, you might be using [can-component] like either:

```js
var can = require("can");

can.Component.extend({ ... });
```

or

```js
var Component = require("can/component/component");

Component.extend({ ... });
```

Regardless of which you are using, update your code to instead look like:

```js
var Component = require("can-component");
<commit_msg>Add info about the StealJS plugins configuration required for steal-stache to the Migration Guide<commit_after>@page migrate-3 Migrating to CanJS 3
@parent guides/commitment 2
@templateRender <% %>
@description This guide walks you through the step-by-step process to upgrade a 2.x app to CanJS 3.
@outline 0

@body

CanJS 3 introduces an even more modular project structure and several new features, while having a minimal number of deprecations and removals from the [2.3 API](//v2.canjs.com/docs/).

This guide goes over:

* [*Pre-migration preparation*](#Pre_migrationpreparation) you can do in your current 2.x project to more easily move to 3.x in the future.
* [The *minimal migration path*](#Minimalmigrationpath), which includes the fewest changes required to upgrade from 2.x to 3.x.
* [The *modernized migration path*](#Modernizedmigrationpath), which includes upgrading your code to match more modern conventions (such as using the new npm packages).
* [The *latest & greatest migration path*](#Latest_greatestmigrationpath), which uses all of the modern libraries we are most excited about (such as [can-define]).
* [How to *avoid future deprecations & removals*](#Avoidfuturedeprecations_removals) in releases after 3.x

## Pre-migration preparation

Before upgrading your project from 2.x to 3.x, make sure your project builds successfully and all the tests pass.

Additionally, you can take the following steps in your CanJS 2.x app to prepare it for migrating to CanJS 3.

### Use the module folders

You can start importing CanJS code in a modular way before moving to CanJS 3.

For example, you might be using [can-component] like this:

```js
var can = require("can");

can.Component.extend({ ... });
```

Update your code to instead look like this:

```js
var Component = require("can/component/component");

Component.extend({ ... });
```

Use the same pattern for the other modules you are using.

Here’s a list of all the `can.` properties in CanJS 2.3 that can be replaced with modular paths:

- `can.autorender` — `can/view/autorender/autorender`
- `can.bindings` — `can/view/bindings/bindings`
- `can.Component` — `can/component/component`
- `can.compute` — `can/compute/compute`
- `can.Construct` — `can/construct/construct`
- `can.Control` — `can/control/control`
- `can.Deferred` — `can/util/deferred`
- `can.define` — `can/map/define`
- `can.ejs` — `can/view/ejs/ejs`
- `can.event` — `can/event/event`
- `can.fixture` — `can/util/fixture`
- `can.LazyMap` — `can/map/lazy/lazy`
- `can.List` — `can/list/list`
- `can.Map` — `can/map/map`
- `can.Model` — `can/model/model`
- `can.Model.Cached` — `can/model/cached/cached`
- `can.mustache` — `can/view/mustache/mustache`
- `can.Object` — `can/util/object/object`
- `can.route` — `can/route/route`
- `can.stache` — `can/view/stache/stache`
- `can.util` — `can/util/util`
- `can.view.callbacks` — `can/view/callbacks/callbacks`

### Replace uses of `can.$`

[`can.$`](//v2.canjs.com/docs/can.$.html) allows you to access the underlying DOM library bundled with CanJS; for example, jQuery in `can.jquery.js`.

You might be using it in your code to easily reference the library:

```js
var can = require("can");
var body = can.$('body');
```

Update your code to explicitly require the library on which you depend. For example:

```js
var $ = require("jquery");
var body = $('body');
```

### Set `leakScope` on components

CanJS 2.2 introduced [can-component.prototype.leakScope leakScope: false] as a property on a [can-component]. This prevents values in parent templates from leaking into your component’s template. In CanJS 3, **leakScope** is now `false` by default.

If you have a template like:

```
<some-component></some-component>
```

That you render with a [can-map map] containing a `page` property like so:

```js
render(new Map({
	page: "home"
}));
```

This `page` property is not available within `some-component`’s own template.

If the component’s template looks like:

```
<h1>Hello {{page}}</h1>
```

It can only lookup the `page` property on `some-component`’s own [can-component.prototype.ViewModel]. To restore the behavior in 2.x, simply set [can-component.prototype.leakScope] to be `true` on the component:

```js
Component.extend({
	tag: "some-component",
	ViewModel: ...,
	leakScope: true
});
```
@highlight 4

## Minimal migration path

If you are already using `can` through npm, simply run the following command to install the latest version:

```
npm install can --save
```

This will update your `package.json` to look something like this:

```js
{
  ...
  "dependencies": {
    "can": "^<%canjs.package.version%>"
  }
}
```

The `^` ensures you get minor and patch releases as those are released.

At a minimum, to upgrade your code for CanJS 3, you must make all of the following changes to your code:

### Use `can/legacy`

In your code where you normally would import `can`, instead import `can/legacy`:

```js
var can = require("can/legacy");
```

This will give you a `can` object with *most* of the same APIs as in 2.3, with a few exceptions:

* [can.mustache](v2.canjs.com/docs/can.mustache.html) is not included with `can/legacy`, but it can still be installed as a [separate package](https://www.npmjs.com/package/can-mustache).
* The former `can.view` functionality no longer exists; see below for more details.

### Asynchronous `inserted` & `removed` events

In your [can-component]s, the [can-util/dom/events/inserted/inserted inserted] and [can-util/dom/events/removed/removed] events were previously fired synchronously as the element was inserted or removed from the DOM. To improve performance, these events are now fired asynchronously.

There is now a [can-component/beforeremove] event that fires synchronously in case you need to perform memory cleanup. For example, you might need to access the parent’s viewModel:

```js
Component.extend({
	tag: "my-panel",

	events: {
		"beforeremove": function(){
			canViewModel(this.element.parentNode).removePanel(this.viewModel);
		}
	}
}
```

### Replace uses of `can.view`

The `can.view` methods have been removed in CanJS 3. The most common use was to create a template renderer from a script element within the page.

Instead of:

```js
var render = can.view('some-id');
```

Just use the DOM APIs and pass the string directly into [can-stache]:

```js
var templateString = document.getElementById('some-id').innerHTML;
var render = stache(templateString);
```

If you were using `can.view.preload` then use [can-stache.registerPartial] instead.

```js
stache.registerPartial("some-id", renderer);
```

### Use native Promises

Native [Promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) are used instead of jQuery promises which means you need to:

* Include a Promise polyfill if targeting browsers that do not have native support. [Steal](http://stealjs.com/) includes a polyfill for you.
* Use `.catch()` instead of `.fail()`.
* Use `.then()` instead of `.done()`.

Note that only a single value is returned from a native Promise.

### Passing the `this` value to a helper

[can-stache] now passes a [can-compute] to [can-stache.Helpers helpers].

If you were passing the `this` value to a helper like so:

```
{{helper .}}
```

You can fix this either by having your helpers handle computes, or by using [can-stache/expressions/call call expressions] instead:

```
{{helper(.)}}
```

### No more global scope names

Most recently-built applications do not depend on adding to the global namespace, but in case you have code that does:

```js
Construct.extend("foo.bar", ...)
```

Which sets `window.foo.bar`, this argument is no longer accepted by [can-construct]. If you *really* need to set a global, you can do so yourself using the return value of [can-construct.extend].

Instead, the first argument to [can-construct.extend] is the name of the constructor function. This is nice for development as you’ll get named objects in your dev tools.

### Using `steal-stache` for templates

If you use StealJS, you’ll need to install [steal-stache] to load your templates:

```
npm install steal-stache --save
```

If you’re using StealJS 0.16, you don’t need to do anything else to make your templates load correctly.

If you’re using StealJS 1, you also need to add `steal-stache` to the `plugins` configuration in your `package.json`:

```json
{
  ...
  "steal": {
    ...
    "plugins": ["steal-stache"]
  }
}
```

## Modernized migration path

CanJS 3 is divided into separate npm packages. This allows us to more quickly update parts of CanJS without affecting other functionality.

In addition to the above, take advantage of the individual packages by installing and using them directly to set your project up for easier upgrades in the future.

For example, you might be using [can-component] like either:

```js
var can = require("can");

can.Component.extend({ ... });
```

or

```js
var Component = require("can/component/component");

Component.extend({ ... });
```

Regardless of which you are using, update your code to instead look like:

```js
var Component = require("can-component");

{'fraction_non_alphanumeric': 0.12401805114491057, 'fraction_numerical': 0.004234219176555797, 'mean_word_length': 4.3059414720662135, 'pattern_counts': {'":': 8, '<': 15, '<?xml version=': 0, '>': 15, 'https://': 4, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6336863', 'n_tokens_mistral': 5645, 'n_tokens_neox': 5341, 'n_words': 2224}