Script Compatibility Mode coming to WaniKani this week

We’re adding Script Compatibility Mode to WaniKani. You can turn it on in the WaniKani settings page WaniKani — Log in

Script Compatibility Mode will let script users stay on a version of WaniKani that works with scripts that are important to them.

We’re enabling Script Compatibility Mode this week to fix a longstanding performance issue for some iOS users with lessons. Unfortunately the performance improvement comes through using React which changes some HTML behavior that scripts rely on.

We’ve been doing some under the hood changes to clean up our code, improve performance and fix bugs. Most of these changes were possible to do while maintaining the same JavaScript, CSS and HTML that scripts expect. We’ve also been trying to give adequate time for users and script authors to review changes on

However, as we work on more significant changes it becomes harder to maintain some code that scripts rely on. We’d also like to share improvements and fixes sooner with users who don’t rely on scripts.

There will be more changes to support Script Compatibility Mode. We’ll be adding a section to the knowledge guide to detail what’s excluded from Script Compatibility Mode. We’ll also add a way for scripts to check the version of WaniKani so scripts can determine if they are compatible or not.

Similar to other changes like API and mnemonics there will be a deprecation schedule for Script Compatibility.

Finally, I want to emphasize that we’ll still aim for improvements that work for both script and non-script users and Script Compatibility Mode will be a last resort.


I assume the idea is that script compatibility mode acts sort of like Microsoft’s Windows update channels for businesses that update more slowly/less frequently compared to the default but still eventually provides all updates? I’m not sure if you do this already but it would be really nice if all client side code was affected by this preference and not just changes gated behind feature flags. (Since in the past, there have been updates that were not gated behind feature flags which broke scripts.)


Compatibility mode changelog via the WaniKani Knowledgebase that was mentioned in the original post

I’ve been meaning to mention this, but I don’t think this compatibility mode is a great long term solution. All it’s going to do is fracture the script community. People will build new scripts for the new page version, and then people on compatibility mode will be stuck only able to use older scripts. I doubt most script developers are going to build and maintain two versions, so I don’t see how the outcome will be anything other than fracturing the community.

It seems to me that it might be better in the long term to add more hooks into the app workflow, which would be kept consistent no matter what, similar to a public API. For example, a window-scoped method for initializing the review queue or for getting the next item off of the review queue, which scripts could then overwrite. In terms of things like double check scripts, there could be hooks into the method that evaluates whether a review is correct, whether to display a warning message (and the specific message), etc. Obviously you won’t be able to support all possible scripts with something like that, but I wonder if this approach would allow you could more consistently support a handful of commonly modified parts of the lesson and review workflow.

1 Like

Yeah I can see this being a huge problem. But I can also see WK’s point here in that they have to be able to evolve their software and that will inevitably break scripts that are relying upon html and css to never change. Scripts, by their very nature, are fragile that way.

@viet I think a partial solution would be for WK to bring the N most popular scripts in-house and fold them into their software natively. Much like FlamingDurtles did. I have about a dozen scripts that I use on the desktop browser, but of course none of these scripts are applicable to FlamingDurtles but I don’t miss them because the FlamingDurtles author did an extraordinary job implementing the most common features that people use scripts for.


Tried addressing this recently. The main files for reviews and lessons are now completely separate instead of gated by feature flags.

Yes, although admittedly rolling out this approach/setting is more motivated by an immediate need to fix bugs and make other changes, so we still need more time to document the details of the approach.

1 Like

Just to clarify, “compatibility mode” isn’t meant to actively fragment the API, we’re not changing the underlying jStorage or public functions just for the sake of changing them.

Instead, it’s about reducing the guesswork/burden on WaniKani devs, whether a variable can be renamed or a specific implementation can be changed. It’s difficult to figure out which changes are safe. Even if our own tests pass a script may be relying on a specific markup structure, variable name, or implementation.
Basically we don’t have an agreed upon API so we don’t know what we’re breaking.

Hopefully we’re able to move faster with compatibility mode in place, and get our house in order sooner.
At that point we’ll be in a better place to discuss whether to have an official API for the front-end. I think we’ll also be more able to incorporate script features into WaniKani like @skatefriday described.

In the meantime, I’ve been trying to offset the shortcomings of this solution by being responsive. If there’s specific things we ended up dropping that’s causing a script to be stuck in compatibility mode, let me know and we’ll try to reincorporate it.

1 Like

Another thing that it would probably make sense to do is to automatically reset the script compatibility mode setting to disabled each time you update the script compatibility mode version of the site to match the latest version of the site. Otherwise, users might understandably just keep the setting turned on all the time. And if they do that, new changes that break scripts might go unnoticed until they go live in the script compatibility mode version of the site. And if breakage is only noticed at that point, then there is no way for users to temporarily restore the old functionality while script developers fix their scripts.

Edit: alternatively, you could maybe have 3 script compatibility options although that might be more trouble than it’s worth

  • current: latest version of WaniKani site (recommended for developers and non-script users)
  • six week delay: snapshot updated every 6 weeks (recommended for most script users, is not automatically reset)
  • twelve week delay: same but twelve week update interval (recommended only as a temporary way of fixing problems, is automatically reset to the six week delay setting whenever a snapshot update happens every six weeks)

Edit 2: Another issue you will have to decide about is how/whether to handle bug fixes in script compatibility mode. Given that you don’t have unlimited development resources, it seems like it probably makes sense to mostly not backport anything and instead just periodically update the snapshot to match the current site unless there is a huge bug.