diff --git a/README.md b/README.md index 0d73c9bf5..db2e40675 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,6 @@ - LiveDebugger is a browser-based tool for debugging applications written in [Phoenix LiveView](https://github.com/phoenixframework/phoenix_live_view) - an Elixir library designed for building rich, interactive online experiences with server-rendered HTML. Designed to enhance your development experience LiveDebugger gives you: @@ -94,7 +93,7 @@ config :live_debugger, port: 4007, # Port on which LiveDebugger will be hosted secret_key_base: "YOUR_SECRET_KEY_BASE", # Secret key used for LiveDebugger.Endpoint signing_salt: "your_signing_salt", # Signing salt used for LiveDebugger.Endpoint - adapter: Bandit.PhoenixAdapter # Adapter used in LiveDebugger.Endpoint + adapter: Bandit.PhoenixAdapter, # Adapter used in LiveDebugger.Endpoint tracing_setup_delay: 0 # Time in ms after tracing will be initialized. Useful in case multi-nodes envs ``` diff --git a/docs/config.md b/docs/config.md new file mode 100644 index 000000000..5874b990a --- /dev/null +++ b/docs/config.md @@ -0,0 +1,39 @@ +### Browser features + +Some features require injecting JS into the debugged application. They are enabled by default, but you can disable them in your config. + +```elixir +# config/dev.exs + +# Disables all browser features and does not inject LiveDebugger JS +config :live_debugger, browser_features?: false + +# Disables only debug button +config :live_debugger, debug_button?: false +``` + +### Content Security Policy + +In `router.ex` of your Phoenix app, make sure your locally running Phoenix app can access the LiveDebugger JS files on port 4007. To achieve that you may need to extend your CSP in `:dev` mode: + +```elixir + @csp "{...your CSP} #{if Mix.env() == :dev, do: "http://127.0.0.1:4007"}" + + pipeline :browser do + # ... + plug :put_secure_browser_headers, %{"content-security-policy" => @csp} +``` + +### Other + +```elixir +# config/dev.exs + +config :live_debugger, + ip: {127, 0, 0, 1}, # IP on which LiveDebugger will be hosted + port: 4007, # Port on which LiveDebugger will be hosted + secret_key_base: "YOUR_SECRET_KEY_BASE", # Secret key used for LiveDebugger.Endpoint + signing_salt: "your_signing_salt", # Signing salt used for LiveDebugger.Endpoint + adapter: Bandit.PhoenixAdapter, # Adapter used in LiveDebugger.Endpoint + tracing_setup_delay: 0 # Time in ms after tracing will be initialized. Useful in case multi-nodes envs +``` diff --git a/docs/images/banner.jpg b/docs/images/banner.jpg new file mode 100644 index 000000000..ffd726d68 Binary files /dev/null and b/docs/images/banner.jpg differ diff --git a/docs/images/logo.png b/docs/images/logo.png new file mode 100644 index 000000000..f043c5d03 Binary files /dev/null and b/docs/images/logo.png differ diff --git a/docs/welcome.md b/docs/welcome.md new file mode 100644 index 000000000..3c3693aec --- /dev/null +++ b/docs/welcome.md @@ -0,0 +1,63 @@ +![LiveDebugger_Chrome_WebStore](images/banner.jpg) + +LiveDebugger is a browser-based tool for debugging applications written in [Phoenix LiveView](https://github.com/phoenixframework/phoenix_live_view) - an Elixir library designed for building rich, interactive online experiences with server-rendered HTML. + +Designed to enhance your development experience LiveDebugger gives you: + +- A detailed view of your LiveComponents tree +- The ability to inspect assigns for LiveViews and LiveComponents +- Tracing of their callback executions + +## Installation + +> #### Important {: .info} +> +> LiveDebugger should not be used on production - make sure that the dependency you've added is `:dev` only + + + +### Mix installation + +Add `live_debugger` to your list of dependencies in `mix.exs`: + +```elixir + defp deps do + [ + {:live_debugger, "~> 0.1.6", only: :dev} + ] + end +``` + +For full experience we recommend adding below line to your application root layout. It attaches `meta` tag and LiveDebugger scripts in dev environment enabling browser features. + +```elixir + # lib/my_app_web/components/layouts/root.html.heex + + + <%= Application.get_env(:live_debugger, :live_debugger_tags) %> + +``` + +After you start your application, LiveDebugger will be running at a default port `http://localhost:4007`. + +### Igniter installation + +LiveDebugger has [Igniter](https://github.com/ash-project/igniter) support - an alternative for standard mix installation. It'll automatically add LiveDebugger dependency and modify your `root.html.heex` after you use the below command. + +```bash +mix igniter.install live_debugger +``` + + + +## Authors + +LiveDebugger is created by Software Mansion. + +Since 2012 [Software Mansion](https://swmansion.com/?utm_source=git&utm_medium=readme&utm_campaign=livedebugger) is a software agency with experience in building web and mobile apps as well as complex multimedia solutions. We are Core React Native Contributors, Elixir ecosystem experts, and live streaming and broadcasting technologies specialists. We can help you build your next dream product – [Hire us](https://swmansion.com/contact/projects). + +Copyright 2025, [Software Mansion](https://swmansion.com/?utm_source=git&utm_medium=readme&utm_campaign=livedebugger) + +[![Software Mansion](https://logo.swmansion.com/logo?color=white&variant=desktop&width=200&tag=livedebugger-github)](https://swmansion.com/?utm_source=git&utm_medium=readme&utm_campaign=livedebugger) + +Licensed under the [Apache License, Version 2.0](LICENSE) diff --git a/mix.exs b/mix.exs index 6defb00b5..80f34b12d 100644 --- a/mix.exs +++ b/mix.exs @@ -77,10 +77,19 @@ defmodule LiveDebugger.MixProject do defp docs() do [ - main: "readme", - extras: ["README.md", "LICENSE"], + main: "welcome", + logo: "./docs/images/logo.png", + extras: [ + "docs/welcome.md": [title: "Welcome to LiveDebugger"], + "docs/config.md": [title: "Configuration"] + ], source_url: "https://github.com/software-mansion/live-debugger", - source_ref: @version + source_ref: @version, + api_reference: false, + assets: %{Path.expand("./docs/images") => "images"}, + filter_modules: fn module, _meta -> + module == Mix.Tasks.LiveDebugger.Install + end ] end