Installing backpex via generator

[phyr97]

closes #980

This is the starting point for a backpex installer with igniter. You can use mix igniter.install backpex to add backpex to your project and have almost everything set up without any further work. More information about installing with igniter can be found in its docs.

The installer requires the new tailwind and daisyui update (#920), as it greatly reduces the pain of the tailwind and daisyui setup (no tailwind.config.js :partying_face:).

ToDo

• [x] Install the backpex hooks via igniterjs
  • requires igniterjs to be installed in the user's project
• [x] Install daisyui using npm command
  • checks if npm is installed and asks the user if the installer is allowed to install daisyui
• [x] add backpex to `.formatter.exs
• [x] configure pubsub server in `config.exs
• [x] add backpex_routes to router.exs.
• [x] add admin.html.heex to layouts folder
• [x] add @source "../../deps/backpex/**/*.*ex"; to app.css
• [x] warn user if tailwindcss/forms plugin exists in app.css
  • can be removed by the generator if the user confirms it
• [x] warn user if bg-white class is used on body tag
  • can be removed by the generator if the user confirms it
• [x] write docs
• [x] test manually with new phoenix project
• [x] improve code
• [x] fix credo warnings and possible bugs discovered while testing
• [ ] write tests for the generator with Igniter.Test

[Flo0807]

I cannot start the demo app:

app-1       | * sourceror (Hex package)
app-1       |   the :only option for dependency sourceror
app-1       |
app-1       |   > In mix.exs:
app-1       |     {:sourceror, "~> 1.7", [env: :prod, hex: "sourceror", only: [:dev, :test], repo: "hexpm"]}
app-1       |
app-1       |   does not match the :only option calculated for
app-1       |
app-1       |   > In deps/rewrite/mix.exs:
app-1       |     {:sourceror, "~> 1.0", [env: :prod, hex: "sourceror", repo: "hexpm", optional: false]}
app-1       |
app-1       |   Remove the :only restriction from your dep
app-1       | ** (Mix) Can't continue due to errors on dependencies

I removed sourceror from the list of dependency in demo/mix.exs and it works. I think the error occurs because sourceror is a dependency of igniter (?)

[Flo0807]

This installer automates most of the steps in this guide.

As the installer does not automate all the steps from our guide, the docs should make it clear where you have to continue.

My idea would be to sort the installation guide to first cover the steps the installer can do for you, and then list all the other steps. Then we can link to the section where you can continue.

Also, we should move the info for the installer task below the Prerequisites section as you are required to have Tailwind CSS v4 installed for example. I guess, we can remove the Prerequisites title at all and just list all the steps.

This is the order I came up with

(Prerequisites) - as you need to perform the below steps to be able to run the generator

• Phoenix LiveView
• Tailwind CSS
• Ecto (we could move this to the steps after running the generator)
• Add to list of dependencies

Generator hint / info (below steps are covered by the generator)

• Global configuration
• Backpex Hooks
• daisyUI (installation)
• Add files to Tailwind content
• Setup formatter
• Configure Routing (without routes to LiveResources, just backpex_routes and import Backpex.Router)
• Create a default admin layout
• Remove default background color
• Remove @tailwindcss/forms plugin

Continue Hint (steps running the generator)

• Create an example resource
• Configure LiveResource
• Configure Routing (live_session, init_assigns, route to example live_resource, default route, link in sidebar etc)
• Provide Tailwind Plugin for heroicons
• daisyUI theme

Without reordering the installation guide, it is not clear where you have to continue after you've run the command.

[Flo0807]

This installer automates most of the steps in this guide.

As the installer does not automate all the steps from our guide, the docs should make it clear where you have to continue.

My idea would be to sort the installation guide to first cover the steps the installer can do for you, and then list all the other steps. Then we can link to the section where you can continue.

Also, we should move the info for the installer task below the Prerequisites section as you are required to have Tailwind CSS v4 installed for example. I guess, we can remove the Prerequisites title at all and just list all the steps.

This is the order I came up with

(Prerequisites) - as you need to perform the below steps to be able to run the generator

• Phoenix LiveView
• Tailwind CSS
• Ecto (we could move this to the steps after running the generator)
• Add to list of dependencies

Generator hint / info (below steps are covered by the generator)

• Global configuration
• Backpex Hooks
• daisyUI (installation)
• Add files to Tailwind content
• Setup formatter
• Configure Routing (without routes to LiveResources, just backpex_routes and import Backpex.Router)
• Create a default admin layout
• Remove default background color
• Remove @tailwindcss/forms plugin

Continue Hint (steps running the generator)

• Create an example resource
• Configure LiveResource
• Configure Routing (live_session, init_assigns, route to example live_resource, default route, link in sidebar etc)
• Provide Tailwind Plugin for heroicons
• daisyUI theme

Without reordering the installation guide, it is not clear where you have to continue after you've run the command.

I prepared the docs in https://github.com/naymspace/backpex/pull/1098 @phyr97

[phyr97]

I would recommend to test the installer with this command:

mix igniter.install backpex@git:https://github.com/naymspace/backpex.git@feature/backpex-installer

You also need to install igniter before using this command. You can use the archive or install it in the mix.exs