~sbaildon/yemma

yemma/guides/quickstart.md -rw-r--r-- 3.0 KiB
0ff0d5ceSean Baildon no gettext compiler nedded a month ago

#Quickstart

#Installation

  1. Install Yemma as a dependency in your app

    # mix.exs
    defp deps do
       [
          ...,
          {:yemma, git: "https://git.sr.ht/~sbaildon/yemma"}
       ]
    end
    
  2. Fetch and install dependencies

    mix deps.get
    
  3. Generate migrations for your user and token tables

    mix ecto.gen.migration add_users_tables
    
  4. Edit your migration file to run the Yemma migrations

    # priv/repo/migrations/*_add_users_tables.exs
    defmodule MyApp.Repo.Migrations.AddUsersTables do
      use Ecto.Migration
    
      defdelegate change, to: Yemma.Migrations
    end
    

#Usage

  1. Create a User and UserToken module

    # lib/my_app/user.ex
    defmodule MyApp.User do
      use Yemma.Users.User
    end
    
    # lib/my_app/user_token.ex
    defmodule MyApp.UserToken do
      use Yemma.Users.UserToken
    end
    
  2. Update your configuration
    You need to generate a secret key that is used to sign the authentication cookies

    mix phx.gen.secret
    
    # config/config.exs
    config :my_app, Yemma,
      repo: MyApp.Repo,
      routes: MyAppWeb.Router.Helpers,
      secret_key_base: $YOUR_SECRET_KEY,
      user: MyApp.User,
      token: MyApp.UserToken,
      endpoint: MyAppWeb.Endpoint,
    
  3. Start Yemma with your application

    # lib/my_app/application.ex
    defmodule MyApp.Application do
      def start(_type, _args) do
        children = [
          ...,
          {Yemma, Application.fetch_env!(:my_app, Yemma)}
        ]
      end
    end
    
  4. Add Yemma's routes to your web application

    # lib/my_app_web/router.ex
    defmodule MyAppWeb.Router do
      import Yemma,
        only: [
          redirect_if_user_is_authenticated: 2,
          require_authenticated_user: 2,
          fetch_current_user: 2,
          prepare_yemma: 2
        ]
    
      pipeline :browser do
        ...
        plug :fetch_current_user
      end
    
      pipeline :yemma do
        plug :prepare_yemma
      end
    
      scope "/", YemmaWeb do
        pipe_through [:yemma, :browser, :redirect_if_user_is_authenticated]
    
        get "sign_in", UserSessionController, :new
        post "sign_in", UserSessionController, :create
    
        get "/confirm/:token", UserConfirmationController, :edit
      end
    
      scope "/", YemmaWeb do
        pipe_through [:yemma, :browser, :require_authenticated_user]
    
        get "/settings", UserSettingsController, :edit
        put "/settings", UserSettingsController, :update
        get "/settings/confirm_email/:token", UserSettingsController, :confirm_email
    
        delete "/sign_out", UserSessionController, :delete
      end
    
      # Protect routes with :require_authenticated_user
      scope "/protected", MyAppWeb do
        pipe_through [:browser, :require_authenticated_user]
    
        get "/", MyProctedController, :index
      end
    end