Directus 9 is finally here, and it’s the biggest update we’ve released in the past 15 years. This article will describe what changed in this new version, and give some insight into the reasoning behind our more far-reaching decisions.
To start off, let’s cover the biggest change in this release — our move from PHP to Node.js.
Why Node.js?
Previous versions of Directus were built on PHP-Zend, but with Zend being deprecated, we decided it was time to port our API to PHP-Laravel. We started in on that refactor in January 2020, but progress was slower than expected. Around March, Rijk (our tech lead) decided to spend a weekend building a proof-of-concept of our API in Node — which we had been informally discussing for years.
Not only was development of the Node PoC quicker than expected, the API responses were coming through about 10x faster than v8. With such promising results, we officially started building both v9 APIs (PHP-Laravel and Node) in parallel.
Months later, we reassessed the state of each port to see which would take the lead and officially define the Directus specification. Our team loved the idea of having the entire platform written in a single language — and it helped that all of our engineers were very comfortable with JavaScript/TypeScript. So in the end, we opted to have Node be the official API port, and therefore define the Directus specification.
That being said, we are still actively working on the PHP-Laravel API for Directus 9. As of now, it’s expected to be released in early 2021, and will be mostly community-driven, while our internal team focuses on the Node flavor of Directus.
New Features & Improvements
Okay, now on to the good stuff. What’s new in Directus 9? Let’s start with some of the bigger items...
Database abstraction is now handled by Knex, and we’ve expanded our official support to include: MySQL, PostgreSQL, SQLite, Microsoft SQL Server, Oracle DB, and variants such as MariaDB, AWS RedShift, AWS Aurora, and more.
Permissions are now defined by customizable filters and rules — making access control completely open-ended. Set granular CRUD rules for item access, field access, validation, and even field value defaults. We even have a set of dynamic variables that can be filtered against, such as NOW, CURRENT_USER, and CURRENT_ROLE.
Many-to-Any (sometimes called a page builder, dynamic zone, etc) has been one of the most requested features for years, and it’s finally here with Directus 9. Now you can create relationships that span any number of collections — opening the door to pretty much any type of data models.
Displays are one of the new building blocks within the Directus App. In previous versions, Interfaces handled the interaction and presentation of a field throughout the app, but that led to a lot of duplicate code — so we decoupled these into Interfaces for managing values on the detail page, and Displays for inline presentation of values.
Performance has been improved across the board. Our internal query builders have been rewritten and optimized to be as fast as possible. In addition to the actual I/O speeds, we’ve added native support for Caching via Redis or memory.
Nestable Folders are another feature that has been high on our list for a while, and now it’s ready for prime-time. Now you can better organize your assets, and even include default folders for new uploads. Drag-and-drop coming soon.
Dataset Export is finally here. Filter your content, and then simply request it in JSON or CSV to get a raw export. Data Import Mapping and full database backups via the API are in-work and coming soon.
Built-In Docs and a Tailored API Reference. This is huge. While our API has always conformed to your custom SQL database, this is the first version to give you a dynamic reference for all your collection and field endpoints. We’ve also added versioned docs built right in to the App, giving you quick access to guides, concepts, and other info.
These are just some of the biggest updates in Directus 9, but the list goes on. All of our modules now support their own navigation bar, we’ve included a preset/bookmark manager, collections now have proper pagination, modals have been converted to larger “drawers”, and field setup has been completely reimagined.
But perhaps more important than any new feature, is the number of bugs we’ve squashed with this refactor. From annoying topical issues, to deep-seated technical debt created over the past decade, we’ve taken great care to ensure this is the most stable version of Directus ever. We’ve reorganized the codebase, combined repositories, and done everything possible to make fixing, maintaining, and contributing as easy as possible.
It’s also important to mention that we’ve completely cleaned house within our GitHub. Not only is Directus 9 now a “monorepo” (combining the App, API, Docs, SDK, builds, and other packages), we also reorganized or archived 60+ legacy repos across the organization. This removes unnecessary noise, making it easier to find what you’re looking for, report issues, and contribute. So if you’re looking for a v8 repo that seems to be missing, chances are it was combined into the v8-archive monorepo.
What’s in this breaking change?
So now that we’ve covered a few of the exciting advancements of Directus 9, let’s talk about what you’ll need to be aware of when updating to v9 from previous versions. If you’re starting with Directus fresh, you can safely ignore this section, unless you’re just curious about how we handle breaking changes like this.
Once we decided that Directus 9 would be a full refactor (App, API, Docs, and SDK), we wanted to make sure we had complete freedom to correct any fundamental issues inherited from legacy versions. We don’t take breaking changes lightly, and knew that this would be our only chance for the next few years to optimize the I/O of the platform, and so we spent months researching and strategizing around exactly how to approach this update. Below are the details...
After the switch from PHP to Node, the next biggest update in v9 was the removing of database multitenancy. Previous versions of Directus allowed a single instance to manage multiple databases by creating different config files, and scoping all endpoints within a project key. While the idea of this is great, it significantly muddled the codebase and added a lot of confusion for users. Also, our new rule-based permissions allows for multitenancy within a single database, and installing new instances became much easier via npm — so we opted to keep things simple.
In addition to the removal of the project scope in the API, there have been a number of various smaller changes to the endpoints. We are aiming to have a definitive list of all these differences soon, but in the meantime, you can rest assured that roughly 80%+ of the API I/O is the same as in v8.
The only other notable breaking change in v9 involves how system data is stored. As you can imagine, all those awesome features and enhancements listed above require a significantly different system schema. And some, such as our completely new permissions system, are so incompatible that there’s no way to automate the migration of settings between versions. This unfortunately means that there is no magic “update” button that can upgrade everything from v8 to v9. But fear not, there’s hope!
The guiding principle of Directus is “database mirroring”, which means that all of your user data is always stored in pure SQL, completely pristine and unaltered. That means that no matter where it comes from (eg: a random SQL database, or a previous version of Directus), you’re always able to seamlessly migrate your content.
So in a nutshell, here’s what updating from v8 would look like:
- Install Directus 9 fresh
- Import your legacy data tables with all content
- Reconfigure fields and permissions in v9
We realize that this process is less than ideal, but it’s the only way that we could properly modernize and optimize Directus 9. Our promise to you is that we will remain judicious with these breaking changes, and keep them as infrequent as possible.
What’s next?
All this is only the beginning. Our entire team has been hard at work for over a year, and we have a whole lot of other things that will be coming over the next few days, weeks, and months. Below are just a few of the things we’re pushing soon.
- First and foremost, we’ll be focusing on Directus 9 stability. Amidst all the other things we’re working on, this will always take priority.
- Documentation is a close second to stability — as intuitive as Directus is, it’s crucial to have proper docs for various installation methods, edge-case configurations, and building custom extensions. In addition to the built-in docs mentioned above, look for our new/updated v9 public docs in the next few days.
- An all new Directus also warrants an all new Cloud platform. We are wrapping up testing on our Standard Cloud and Enterprise Cloud systems, complete with a redesigned dashboard. Expect updates on this in the next few weeks.
- While our free-for-all public demo has treated us well over the past few years, it’s time to move on. Soon after our new Cloud service is released we’ll be offering free, fully-automated private demo instances. Gone are the days of waiting for the password to reset on the hour, or coming across offensive content from trolls.
- While our Directus Slack channel has passed 3,000 members, we felt that their free-tier was too limiting for our community chat (and too pricey for FOSS). We have therefore opted to migrate our core team and v9 community conversations over to Discord — come and join us!
- We’ll be adding more interfaces, displays, modules, and more to the core codebase, but are also working on our Extension Marketplace. This will be a way to browse (and install) external extensions that you or other members of the community have created.
- Lastly, you may have seen our new marketing website, in fact, you’re probably reading this article on it. We feel this new design system better captures the aesthetic and ethos of our new ecosystem, and helps unite all of our growing products and services.
Thanks for taking the time to learn about Directus 9 — we sincerely hope you love what we’ve worked so hard to create. If you have any questions, come join us on Discord!