Migration is totally optional, and backwards compatibility is intended to be kept for as long as we can. It is recommended to migrate, as the new api is easier to use and adds new features, but there is no major rush to get this done.
You can see a full migration example here, although this also makes some actual functional changes in
main.py[todo: point to specific commits later]
The new API is only supported in decky 3.0 and later.
The python library decky_plugin has been renamed to decky, but all pre-existing methods are unchanged there and the old decky_plugin name is still provided for convenience, so no changes should be required on the python end.
In the frontend, decky-frontend-lib has been split into two libraries, @decky/api and @decky/ui. DFL's ServerAPI has been completely removed, and replaced by new functions in @decky/api.
@decky/ui contains all the react components and similar from DFL, largely unchanged. Aside from removing all ServerAPI usage and a couple other functions, a simple rename of decky-frontend-lib should work.
@decky/api contains all the other functions that aren't just react elements.
For calling the backend, ServerAPI.callPluginMethod has been replaced by call which has a very similar interface, but it returns its result directly, instead of through an intermediary interface. Any backend errors will be raised and bubble up as JS errors.
// before
import { ServerAPI } from "decky-frontend-lib";
interface AddMethodArgs { a: number; b: number; }
const res = await serverAPI.callPluginMethod<AddMethodArgs, number>("add", {a: 1, b: 2});
if (res.success) {
console.log(res.result);
}
// after
import { call } from "@decky/api";
const res = await call<[a: number, b: number], number>("add", 1, 2);
console.log(res);
Various methods like toaster, routerHook, openFilePicker, executeInTab, injectCssIntoTab, removeCssFromTab, fetchNoCors, getExternalResourceURL and definePlugin have been moved to @decky/api. They are unchanged so you will just need to change where you import them from.
You can read more about using the new api here
You need to add "api_version": 1, so decky knows which version of the api to serve you.
Remove all references to decky-frontend-lib from the file completely.
Add @decky/api and @decky/ui to your dependencies.
Add @decky/rollup to your devDependencies.
Add "type": "module" just below where you set the name and description.
The file has been renamed (because the library was renamed), and has extra fields for the new backend functions. Copy it in from the template or from decky.
The new @decky/rollup dependency you added means this is all set up properly for you by just importing deckyPlugin and using that as your rollup config.
import deckyPlugin from "@decky/rollup";
export default deckyPlugin({
// Add your extra Rollup options here
)