Fireside (fireside v0.2.0)
View SourceThis is the documentation for the Fireside project.
Summary
Functions
Checks if the provided component is installed in the current project.
Installs a Fireside component into the project.
Uninstalls a Fireside component from the project.
Unlocks a Fireside component, removing it from Fireside's tracking without deleting it.
Updates a previously installed Fireside component.
Functions
Checks if the provided component is installed in the current project.
Examples
iex> Fireside.component_installed?(:example_component)
falseInstalls a Fireside component into the project.
This is done by importing files listed in config/0 (in fireside.exs) of the target component.
If the component defines a setup/1 method, it will also be called.
Parameters
component_name: The name of the component to install. It can be an atom or a string.source: The source from which to install the component. The supported formats are:[path: component_path]: Install from a local path.[{:git, git_url} | git_opts]: Install from a Git repository.git_optscan include:ref,:branch, or:tag.[{:github, github_repo} | git_opts]: Install from a GitHub repository.git_optscan include:ref,:branch, or:tag.
opts: A keyword list of options. Supported options include::unlocked?- When true, the component is installed without being tracked by Fireside.:yes?- When true, auto-accepts all prompts during installation.:no_hash?- When true, skips adding hash to files and .fireside.exs.
Examples
iex> Fireside.install(:my_component, [path: "/path/to/component"], unlocked?: true)
:ok
iex> Fireside.install(:my_component, [git: "https://github.com/user/repo.git"] ++ [tag: "v1.0.0"])
:ok
iex> Fireside.install(:my_component, [github: "user/repo"] ++ [branch: "main"])
:okUninstalls a Fireside component from the project.
This function will attempt to remove all files and configurations associated with the component that were managed by Fireside. However, there are certain manual steps you may need to perform after the uninstallation; read more in the "Warning" below.
Parameters
component_name: The name of the component to uninstall. It can be an atom or a string.opts: A keyword list of options. Supported options include::yes?- When true, auto-accepts all prompts during the uninstallation.
Warning
After uninstalling a component, you may need to manually:
- Remove Optional or Manually Added Files: If the component installation added files that were not tracked by Fireside
(e.g., files that were marked as
:optionalor added outside the standard component structure via Igniter), these will not be automatically deleted. You will need to identify and remove these files yourself, if needed. - Cleanup Configuration Changes: If the component installation modified configuration files
(e.g.,
config/config.exs,config/dev.exs), these changes will not be reverted automatically. Review these files and manually remove any settings or configurations related to the uninstalled component. - Remove Unused Dependencies: Dependencies installed alongside the component will not be automatically
removed, as Fireside cannot determine if they are used elsewhere in your project. You may need to manually
remove these dependencies from your
mix.exsfile and runmix deps.cleanto fully remove them from your project.
Examples
iex> Fireside.uninstall(:my_component)
:okUnlocks a Fireside component, removing it from Fireside's tracking without deleting it.
This is useful if you want to continue using the component but no longer want it to be managed by Fireside.
Parameters
component_name: The name of the component to unlock. It can be an atom or a string.opts: A keyword list of options. Supported options include::yes?- When true, auto-accepts all prompts during the unlock process.
Examples
iex> Fireside.unlock(:my_component)
:okUpdates a previously installed Fireside component.
This is done by reimporting files listed in config/0 (in fireside.exs) of the target component.
If the component's version is being changed and a corresponding upgrade/3 migration is defined,
it will also be executed. (Note: multiple upgrade/3 migrations may be executed if the app's
version is changed by more than 1.)
Before updating, the integrity of the installed component will be checked by comparing the hash
of the AST with the hash listed in config/fireside.exs. If the installed component has been
modified and has diverged from its original source, the operation will be aborted, as it might
lead to a regression since any added/removed functionality may be overwritten by remote updates.
In this case, it is recommended to run unlock/2 to instruct Fireside to stop tracking the
component's source.
Parameters
component_name: The name of the component to update. It can be an atom or a string.source: The source from which to update the component. Ifnil(default), the source from the local component configuration is used. Otherwise, the supported formats are:[path: component_path]: Install from a local path.[{:git, git_url} | git_opts]: Install from a Git repository.git_optscan include:ref,:branch, or:tag.[{:github, github_repo} | git_opts]: Install from a GitHub repository.git_optscan include:ref,:branch, or:tag.
opts: A keyword list of options. Supported options include::yes?- When true, auto-accepts all prompts during the update.:force?- When true, skips integrity check and overwrites files.:no_hash?- When true, skips adding hash to files and .fireside.exs.
Examples
iex> Fireside.update(:my_component)
:ok
iex> Fireside.update(:my_component, [git: "https://github.com/user/repo.git"] ++ [branch: "dev"])
:ok