[blue219]

Brief summary

Begin an incremental migration of the backend from JavaScript to strict TypeScript. Preserve API responses, database compatibility, CommonJS exports, and initialization order while migrating in small, reviewable batches.

The checklist below describes the proposed remaining migration.

Scope and working approach

The source inventory contains 428 backend JS files: 181 application files under server/, 244 embedded-library files under server/libs/, and 3 root entry/configuration files. There are also 35 backend JS test/helper files. Frontend migration is outside this proposal.

Migration TODO list

• Phase 0 — Preparation: establish validation baselines; define global-variable, embedded-library, and Express request types as needed; ensure new declaration files are loaded by tsconfig.server.json.
• Phase 1 — Foundation: migrate low-dependency files directly under server/utils/, starting with constants, globals, and equivalence helpers, then server/Logger.js and remaining general utilities. Defer query and legacy migration helpers.
• Phase 2 — Objects and parsing: migrate server/objects/files/, server/objects/metadata/, low-dependency direct objects, server/utils/parsers/, and server/utils/generators/. Validate parsing, serialization, and missing fields.
• Phase 3 — Data layer: migrate server/models/, server/Database.js, server/utils/queries/, and server/objects/settings/. Start with simple models and join tables; coordinate complex model, database, and query contracts in small batches.
• Phase 4 — Authentication and sockets: migrate server/auth/, server/Auth.js, and server/SocketAuthority.js. Validate login, refresh, logout, permissions, and socket authentication.
• Phase 5 — Business services: migrate server/providers/, server/finders/, server/managers/, and remaining business objects. Start with providers and finders, then simple and complex managers. Defer migration/scanning managers to their relevant phases.
• Phase 6 — Scanning and watching: migrate server/scanner/, server/Watcher.js, and scanning-coupled managers. Start with scan/probe data objects, then individual scanners and orchestration. Validate first/repeated scans, file changes, and malformed media.
• Phase 7 — Interfaces and startup: migrate server/controllers/, server/routers/, server/Server.js, and root index.js, dev.js, and prod.js. Update compiler includes, ESLint matching, nodemon watch paths, and CI path filters when entry files are renamed.
• Phase 8 — Historical migrations: migrate server/migrations/, server/utils/migrations/, and server/managers/MigrationManager.js. Preserve migration identifiers and compiled .js discovery/copying; validate upgrade and downgrade behavior.
• Embedded-library workstream: agree on the scope of server/libs/; provide boundary types first, then convert libraries individually if source conversion is required. Define validation for these files, which the current ESLint configuration ignores.
• Release readiness: verify the target packaging/deployment path and representative backend flows; confirm the intended migration scope is complete and update documentation.

[nichwall]

Hey, thanks for starting this. I've been in the process of converting the server backend to TS the last few months but this is looking good.

I started from the Controllers to work on getting OpenAPI docs generated and that's pretty much done and I am just in the testing stages. I have not converted the rest of the files yet (I did turn AI loose on a local branch just to see how it did over the entire repo, but it got pretty messy so your PR is a lot cleaner).

l can start a Discussion later to make coordinating easier instead of having to track the progress across several PRs. We will probably want to break the migration into several PRs, because some of the bigger files end up having a lot of changes when the types get more complicated.

One comment is we don't want AGENTS.md committed to the repo right now. AI is a great tool for adding types to things and helping with big updates like this, but we're not ready to add more AI tooling to the repository yet. https://audiobookshelf.org/docs/contributing/general#ai-tools

[blue219]

Hey, thanks for starting this. I've been in the process of converting the server backend to TS the last few months but this is looking good.

I started from the Controllers to work on getting OpenAPI docs generated and that's pretty much done and I am just in the testing stages. I have not converted the rest of the files yet (I did turn AI loose on a local branch just to see how it did over the entire repo, but it got pretty messy so your PR is a lot cleaner).

l can start a Discussion later to make coordinating easier instead of having to track the progress across several PRs. We will probably want to break the migration into several PRs, because some of the bigger files end up having a lot of changes when the types get more complicated.

One comment is we don't want AGENTS.md committed to the repo right now. AI is a great tool for adding types to things and helping with big updates like this, but we're not ready to add more AI tooling to the repository yet. https://audiobookshelf.org/docs/contributing/general#ai-tools

That’s great! I’m very happy to be working with you all! Please let me know if there is anything you need me to do; in the meantime, I will continue moving forward with my plan. As for the AGENTS.md file, you can ignore it.

[nichwall]

Cool. I just looked at the new commits, and please make sure changes can be tracked across the renames (a few of the small files are shown as deleted then added).

It's not as big of a deal with these simple files, but we want to maintain the history of bigger files (such as the managers)

[blue219]

Looks like a lot of these recent commits are not recognized as move/renames. Also, can you please break this up into smaller PRs so it is easier to review?

Sorry for the late reply. I’ve been busy recently.
I’ve started splitting the migration into smaller PRs: #5664, #5665, and #5666. I’ve also separated pure renames from the type changes into dedicated commits.

Could you take a look and let me know whether the scope and approach look reasonable? I’ll address any feedback before submitting the next batches for review.

[nichwall]

Thanks for breaking it up into smaller PRs, that definitely helps. I'm going through them right now so we can start merging changes incrementally as they are reviewed.