Docs site for inertia-django adapter

[SarthakJariwala]

PR adds initial documentation scaffold and setup guides.

Attempts to address #58

To test locally:

• Open and view locally: cd docs && npm i && npm run docs:dev
• Build and preview: npm run docs:build && npm run docs:preview

[BrandonShar]

Thank you, this is amazing @SarthakJariwala !!

I'm out of town right now, but I'll get this merged and start filling in some of the "coming soon" sections this weekend!

[BrandonShar]

Since you have it marked as a draft, are there parts you think we need before merging or is that just because the docs aren't totally complete?

[SarthakJariwala]

Since you have it marked as a draft, are there parts you think we need before merging or is that just because the docs aren't totally complete?

Since initial setup and configuration has been a pain point for new users, I wanted to make sure that "Server side setup" section was complete before merging. I'll try to fill it out soon.
We can add the other missing guides in separate PRs.

There is also another question of where we host the docs. Would we be able to host it under inertiajs GitHub org or should we get a new domain like inertia-rails did? (inerita-django.dev seems available as of now)

[SarthakJariwala]

I thought it would be a good idea to have a template based installation method (similar to inertia-rails). But, if you're not comfortable recommending this approach, I'm ok removing it.

I also have a simpler template based new project setup in another project I'm developing: https://github.com/SarthakJariwala/lfp

In that case, the command would be simpler: uvx lfp new
uvx lfp new uses the currently linked template (gh:sarthakjariwala/django-vite-inertia) under the hood.

From my point of view, either approach would be ok to include, but I do think template based approach is an easier onboarding process compared to manual configuration.

[BrandonShar]

I think it's awesome that you've taken the initiative to set up starter projects! I just want to make sure I understand the setup (a colleague of mine has been encouraging me to switch to uv, but I'm still stuck on poetry).

At a glance, your template works great. My big question relative to other potential starter kits is does your template have a way to keep up with inertia-django tags or is it downstream of them?

[SarthakJariwala]

Thanks! uv definitely feels like the missing piece to python installation and dependency management :-)

The starter project provides only scaffolding - which includes, in my opinion, the most challenging aspect, frontend configuration - integrating Vue, React, or Svelte with django-vite and vite.config.js and inertia.js. The other advantage is also that you get a Dockerfile that you can use for production deployments (if you want one)

The scaffold doesn't utilize any specific features from inertia-django, aside from a basic render call to display the home page and share command in middleware. Therefore, I don't anticipate major issues with maintaining compatibility with future releases of inertia-django.

In the template, the version of inertia-django is specified in the pyproject.toml file to be >=0.6.0, with inertia-django specific configurations located in settings.py. This means that when someone initiates a new project later, they can still utilize this starter template, which will have inertia-django>=0.6.0 in pyproject.toml. Using their preferred dependency resolver (uv or pip), they can install the necessary dependencies, and the resolver will fetch the latest compatible version of inertia-django.

Unless there are specific changes in how inertia-django handles settings or if the render method undergoes a name change, no updates to the inertia-django portion of the template will be required.

The projects that will need closer monitoring are django-vite and inertia.js, as these are more likely to undergo updates impacting the integration. An example would be django-vite changes how it defines dev server settings. In this case, though, docs will also need to be updated - so I don't see it as a major downside.

Let me know if I didn't address your concerns.

---

I do want to mention that we can also just only mention the manual configuration in the docs as the "official" recommendation and remove template based installation. I do understand that you may not want to pick one solution over the others (yet).

I'm also happy to brainstorm and think of a solution that can be integrated into inertia-django the same way inertia-rails has a bin/rails generate inertia:install command that is first party.

[SarthakJariwala]

Related to my comment from earlier: I'm not sure what this should be. I guess it depends on where we decide to host the docs.

[BrandonShar]

I'm double checking right now with some of our users, I'll answer here asap. Thank you for checking!

[navya-sammeta]

Do we really need django-vite here? That's a dependency we can avoid. We can just do vite build for production, and for development it can be vite development server. For production, vite can build the static assets directly into the django static directory. For Dev, we need HMR, and for that vite can do proxy mode. Only thing is, InertiaJS does need is {% block inertia %}{% endblock %} in the html page, that can be done by directly pasting into the html page or using vite-plugin-html, I don't see the need for django-vite dependency.

[SarthakJariwala]

There isn't any explicit dependency on django-vite for inertia-django, but it is mentioned as part of the setup because django-vite does simplify the integration quite a bit, especially for folks new to vite land and for production builds. It is also a very lightweight package and easy to understand, so I don't see many downsides.

Yes, you could just do a vite build and that would be enough if you were bundling all your js into a single file and it would result in a single <link> tag. But, if you were not bundling all js into a single file, manually adding all <link> tags for all different manifest imports will get tedious and very non-ergonomic.

Using vite-plugin-html instead of django-vite feels like replacing one dependency for another, and I don't really see any significant benefits over django-vite.

---

Also, the goal here is to cater to new folks who may not have set up vite integrations before. If you feel comfortable directly integrating vite for production builds, you can ignore this bit of the documentation and use it without django-vite :-)

[navya-sammeta]

But, if you were not bundling all js into a single file, manually adding all tags for all different manifest imports will get tedious and very non-ergonomic

vite does generate the HTML pages as well. All you have to do is something like following. This doesn't require any plugins.

<!doctype html>
<html lang="en">
  <body>
    <div id="root"></div>
    <script type="module" src="/src/main.jsx"></script>
  </body>
</html>

Using vite-plugin-html instead of django-vite

The difference is that, vite-plugin-html is a build dependency while django-vite is a production/runtime dependency. You want to keep your prod surface area as lean as possible from security and maintenance reasons.

[navya-sammeta]

@SarthakJariwala @BrandonShar Bumping this PR. Just checking if we can wrap up this effort. Thank you!

[BrandonShar]

Sorry, I've had this flagged in my reminders and I keep forgetting to come back to it!

@SarthakJariwala remind me what are blockers are right now:

Is it just a registered domain and somewhere to host?

[SarthakJariwala]

@BrandonShar Yes, only blocker is registered domain. I believe we should be able to host on GitHub pages (I've already included a github action in the PR)

A few variations of inertia-django domain are available (.com, .dev and .org)

Another option: If appropriate and the inertia.js team is open to it, we could also host it on the inertiajs.com subdomain (django.inertiajs.com)

[BrandonShar]

Just bought inertia-django.dev !