Packages
igniter
0.5.37
0.8.2
0.8.1
0.8.0
0.7.9
0.7.8
0.7.7
0.7.6
0.7.5
0.7.4
0.7.3
0.7.2
0.7.1
0.7.0
0.6.30
0.6.29
0.6.28
0.6.27
0.6.26
0.6.25
0.6.24
0.6.23
0.6.22
0.6.21
0.6.20
0.6.19
0.6.18
0.6.17
0.6.16
0.6.15
0.6.14
0.6.13
0.6.12
0.6.11
0.6.10
0.6.9
0.6.8
0.6.7
0.6.6
0.6.5
0.6.4
0.6.3
0.6.2
0.6.1
0.6.0
0.5.52
0.5.51
0.5.50
0.5.49
0.5.48
0.5.47
0.5.46
0.5.45
0.5.44
0.5.43
0.5.42
0.5.41
0.5.40
0.5.39
0.5.38
0.5.37
0.5.36
0.5.35
0.5.34
0.5.33
0.5.32
0.5.31
0.5.30
0.5.29
0.5.28
0.5.27
0.5.26
0.5.25
0.5.24
0.5.23
0.5.22
0.5.21
0.5.20
0.5.19
0.5.18
0.5.17
0.5.16
0.5.15
0.5.14
0.5.13
0.5.12
0.5.11
0.5.10
0.5.9
0.5.8
0.5.7
0.5.6
0.5.5
0.5.4
0.5.3
0.5.2
0.5.1
0.5.0
0.4.8
0.4.7
0.4.6
0.4.5
0.4.4
0.4.3
0.4.2
0.4.1
0.4.0
0.3.78
0.3.77
0.3.76
0.3.75
0.3.74
0.3.73
0.3.72
0.3.71
0.3.70
0.3.69
0.3.68
0.3.67
0.3.66
0.3.65
0.3.64
0.3.63
0.3.62
0.3.61
0.3.60
0.3.59
0.3.58
0.3.57
0.3.56
0.3.55
0.3.54
0.3.53
0.3.52
0.3.51
0.3.50
0.3.49
0.3.48
0.3.47
0.3.46
0.3.45
0.3.44
0.3.43
0.3.42
0.3.41
0.3.40
0.3.39
0.3.38
0.3.37
0.3.36
0.3.35
0.3.34
0.3.33
0.3.32
0.3.31
0.3.30
0.3.29
0.3.28
0.3.27
0.3.26
0.3.25
0.3.24
0.3.23
0.3.22
0.3.21
0.3.20
0.3.19
0.3.18
0.3.17
0.3.16
0.3.15
0.3.14
0.3.13
0.3.12
0.3.11
0.3.10
0.3.9
0.3.8
0.3.7
0.3.6
0.3.5
0.3.4
0.3.3
0.3.2
0.3.1
0.3.0
0.2.13
0.2.12
0.2.11
0.2.10
0.2.9
0.2.8
0.2.7
0.2.6
0.2.5
0.2.4
0.2.3
0.2.2
0.2.1
0.2.0
0.1.8
0.1.7
0.1.6
0.1.5
0.1.4
0.1.3
0.1.2
0.1.1
0.1.0
A code generation and project patching framework
Current section
Files
Jump to
Current section
Files
README.md
<img src="https://github.com/ash-project/igniter/blob/main/logos/igniter-logo-small.png?raw=true#gh-light-mode-only" alt="Logo Light" width="250">
<img src="https://github.com/ash-project/igniter/blob/main/logos/igniter-logo-small.png?raw=true#gh-dark-mode-only" alt="Logo Dark" width="250">
[](https://github.com/ash-project/igniter/actions/workflows/elixir.yml)
[](https://hex.pm/packages/igniter)
[](https://hexdocs.pm/igniter)
# Igniter
Igniter is a code generation and project patching framework.
There are two audiences for Igniter:
- **End-users**:
- Provides tasks like `mix igniter.install` to automatically add dependencies to your project
- Provides upgraders to upgrade your deps and apply codemods at the same time
- Provides refactors like `mix igniter.refactor.rename_function` to refactor your code automatically
- **Library authors and platform teams**: Igniter is a toolkit for writing smarter generators that can semantically create _and modify_ existing files in end-user's projects (e.g. codemods)
## For end-users
### Installers
Igniter provides `mix igniter.install`, which will automatically _add the dependency to your mix.exs_ and then run
that library's installer if it has one.
### Upgraders
The `mix igniter.upgrade` mix task is a drop-in replacement for `mix deps.update` but it will additionally
run any upgrade patchers defined in the target package (if there are any).
See the [upgrades guide](/documentation/upgrades.md) guide for more.
### Refactors
In addition to providing tools for library authors to patch your code, common operations are available to use as needed.
- `mix igniter.refactor.rename_function` - Rename a function in your application, along with all references to it. Optionally it can also mark the previous function as deprecated.
### Others
- `mix igniter.update_gettext` - Use this to update [gettext](https://github.com/elixir-gettext/gettext) if your version of gettext is lower than 0.26.1 and you are seeing a compile warning
about gettext backends.
### Installation
#### Standard Installation for end-users
Add Igniter to an existing elixir project by adding it to your dependencies in `mix.exs`:
```elixir
{:igniter, "~> 0.5", only: [:dev, :test]}
```
Note: If you only want to use `mix igniter.install` to add dependencies to your project then you can install the archive instead of adding Igniter to your project.
#### Installing globally via an archive
First, install the archive:
```elixir
mix archive.install hex igniter_new
```
Then you can run `mix igniter.new` to generate a new elixir project
```
mix igniter.new app_name --install ash
```
### Creating a new mix project using Igniter
If you want to create a new mix project that uses ash and ecto you can run a command like:
```
mix igniter.new app_name --install ash,ecto
```
You can also combine an Igniter install command with existing project generators (e.g. `mix phx.new`) by specifying the mix task name with the `--with` flag. If you want to pass arguments to the existing project generator/task you can pass them with `--with-args`:
```
mix igniter.new app_name --install ash --with phx.new --with-args="--no-ecto --no-html"
```
## For library authors and platform teams
Igniter is a toolkit for writing smarter generators that can semantically create _and modify_ existing files.
### Installing for library authors
For library authors, add Igniter to your `mix.exs` with `optional: true`:
```elixir
{:igniter, "~> 0.5", optional: true}
```
`optional: true` ensures that end users can install as outlined above, and `:igniter` will not be included in their production application.
### Patterns
Mix tasks built with Igniter are both individually callable, _and_ composable. This means that tasks can call each other, and also end-users can create and customize their own generators composing existing tasks.
### Installers
Igniter will look for a task called `<your_package>.install` when the user runs `mix igniter.install <your_package>`, and will run it after installing and fetching dependencies.
To create your installer, use `mix igniter.gen.task <your_package>.install`
### Generators/Patchers
Generators created with Igniter can be run like any other mix task, or composed together. For example, lets say that you wanted to have your own `Ash.Resource` generator, that starts with the default `mix ash.gen.resource` task, but then adds or modifies additional files:
To create your generator, use `mix igniter.gen.task <your_package>.task.name`
```elixir
# in lib/mix/tasks/my_app.gen.resource.ex
defmodule Mix.Tasks.MyApp.Gen.Resource do
use Igniter.Mix.Task
@impl Igniter.Mix.Task
def igniter(igniter) do
[resource | _] = igniter.args.argv
resource = Igniter.Code.Module.parse(resource)
my_special_thing = Module.concat([resource, SpecialThing])
location = Igniter.Code.Module.proper_location(my_special_thing)
igniter
|> Igniter.compose_task("ash.gen.resource", igniter.args.argv)
|> Igniter.Project.Module.create_module(my_special_thing, """
# this is the special thing for #{inspect()}
""")
end
end
```
## Upgrading to 0.4.x
You may notice an issue running `mix igniter.upgrade` if you are using `0.3.x` versions.
you must manually upgrade Igniter (by editing your `mix.exs` file or running `mix deps.update`)
to a version greater than or equal to `0.3.78` before running `mix igniter.upgrade`. A problem
was discovered with the process of Igniter upgrading itself or one of its dependencies.
In any case where Igniter must both download and compile a new version of itself, it will exit
and print instructions with a command you can run to complete the upgrade. For example:
`mix igniter.apply_upgrades igniter:0.4.0:0.5.0 package:0.1.3:0.1.4`