Packages

Type checking, .val sources and an LSP for Elixir/Phoenix projects.

Current section

Files

Jump to
valence GETTING_STARTED.md
Raw

GETTING_STARTED.md

# Valence — Getting Started

Guia curto para o Valence 1.0: tipos em Elixir normal, arquivos `.val` e LSP.

## Requisitos

- Elixir **1.20+** (OTP 27+).
- Mix.
- Opcional: Zed para o LSP.

## Instalação

No `mix.exs` do projeto:

```elixir
defp deps do
  [
    {:valence, "~> 1.0", runtime: false}
  ]
end

def project do
  [
    compilers: [:valence, :phoenix_live_view] ++ Mix.compilers(),
    deps: deps()
  ]
end
```

Sem Phoenix, use `compilers: [:valence] ++ Mix.compilers()`.

```bash
mix deps.get
mix compile
```

## Primeiro `.val`

`lib/minha_app/scoring.val`:

```elixir
defmodule MinhaApp.Scoring do
  @spec classificar(non_neg_integer()) :: :low | :mid | :high
  def classificar(score) when score < 50, do: :low
  def classificar(score) when score < 100, do: :mid
  def classificar(_score), do: :high
end
```

O modo estrito exige `@spec` em `def` público, confere o corpo contra o
retorno e trata `case` não-exaustivo como erro. `@impl` isenta callbacks.

```bash
mix compile
mix valence.check "lib/**/*.ex" "lib/**/*.val"
mix valence.type lib/minha_app/scoring.val:2:5
```

## LSP no Zed

Adicione a dep acima e instale a extensão:

1. `Cmd+Shift+P` → **zed: install dev extension** → `zed-valence/`.
2. Abra um `.val`. A extensão inicia `mix valence.lsp` no projeto.
3. Para formatar ao salvar:

```json
"languages": {
  "Val": {
    "formatter": "language_server",
    "format_on_save": "on"
  }
}
```

Fora de um projeto Mix, instale o escript (`mix escript.install hex valence`)
e use `valence lsp`.

## LiveView

```elixir
defmodule MinhaAppWeb.ProducersLive do
  use MinhaAppWeb, :live_view

  @impl true
  def mount(_params, _session, socket) do
    {:ok, assign(socket, :producers, MinhaApp.Producers.list())}
  end

  @impl true
  def render(assigns) do
    ~H"""
    <ul id="producers">
      <li :for={producer <- @producers}>{producer.name}</li>
    </ul>
    """
  end
end
```

Com `reloadable_compilers` no endpoint de dev, alterações em `.val` recarregam
sem reiniciar o servidor:

```elixir
# config/dev.exs
config :minha_app, MinhaAppWeb.Endpoint,
  reloadable_compilers: [:phoenix_live_view, :gettext, :elixir, :valence, :app]
```

## Recursos úteis

- Hover/completion/diagnóstico no LSP, inclusive de Ecto/Phoenix.
- Assigns `@nome` tipados no HEEx.
- PubSub: `handle_info({:evento, payload}, ...)` tipado pelo broadcast.
- Cmd+S formata; Cmd+. oferece `# valence:ignore` e `@impl true`.
- Snippets de callbacks (`mount`, `render`, `handle_event`, …).

## Problemas comuns

| sintoma | causa | correção |
| --- | --- | --- |
| task `valence.*` não encontrada | dep não compilada | `mix deps.get`/`mix compile` |
| LSP não inicia no Zed | projeto sem dep `valence` | adicione a dep e reinicie o LSP |
| hover de função própria em `dynamic()` | sem `@spec` e corpo dinâmico | declare `@spec` |
| `mix format` ignora `.val` | fora dos inputs | adicione `lib/**/*.val` ao `.formatter.exs` |

Mais detalhes: [README.md](README.md) e [docs/VAL_AND_ZED.md](docs/VAL_AND_ZED.md).