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.


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.


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.


This. Flaming Durtles has a lot of the most essential scripts. I had to adjust to it visually (since it looks less sleek than desktop Wanikani), but once I did, I absolutely love it. I constantly study on the go when I have a little bit of time here and there, and I love using it. I actually prefer a couple things about it over desktop Wanikani. I wish Wanikani would incorporate some of the most important scripts (such as what Flaming Durtles uses) into their software. They could allow users to turn them off in the settings if they don’t like those specific features.

@WaniKaniJavi One thing that I can’t find anywhere (but probably has been asked before), what’s your expected time between a change hitting compatibility off and it being the default on both settings? I assume it’s not just “we add a lot of changes, then all of a sudden, compatibility mode is emptied”, but rather it works like a queue

@WaniKaniJavi Ermm… Noob here. I don’t have this option in my settings and I can’t find it anywhere. Help please :sweat_smile:

That person doesn’t seem to be a mod anymore. The function has been removed. You’re better off checking the thread for the scripts you’re using for solutions.

But it appeared just this morning… and I clicked on and now it’s gone and one of my user scripts is not functioning even if I uninstall and install it again. As if it doesn’t exist.

Yes, probably because script compatibility has been removed from the site. That’s why you should check the userscript thread to see if the writer or other coders has a fix/update

1 Like

It was just removed a couple of hours ago.


So basically it should revert back as if nothing happened or if not, I should find another script that does the same thing. Thank you for the info :slight_smile: it was very helpful since I was very confused as to what happened.

1 Like