yusufyildirim / surface

A server-side rendering component library for Phoenix

Surface

Surface is a server-side rendering component library that allows developers to build rich interactive user-interfaces, writing minimal custom Javascript.

Built on top of Phoenix LiveView and its new LiveComponent, Surface leverages the amazing Phoenix Framework to provide a fast and productive solution to build modern web applications.

Full documentation and live examples can be found at surface-ui.org.

Example

# Defining the component

defmodule Hello do
  use Surface.Component

  @doc "Someone to say hello to"
  prop name, :string, required: true

  def render(assigns) do
    ~F"""
    Hello, {@name}!
    """
  end
end

# Using the component

defmodule Example do
  use Surface.Component

  def render(assigns) do
    ~F"""
    <Hello name="John Doe"/>
    """
  end
end

Features

• An HTML-centric templating language, designed specifically to improve development experience.

• Components as modules - they can be stateless, stateful, renderless or compile-time.

• Declarative properties - explicitly declare the inputs (properties and events) of each component.

• Slots - placeholders declared by a component that you can fill up with custom content.

• Contexts - allows a parent component to share data with its children without passing them as properties..

• Compile-time checking of the template structure, components' properties, slots, events and more.

• Integration with editor/tools for warnings/errors, syntax highlighting, jump-to-definition, auto-completion (soon!) and more.

Installation

Phoenix v1.5 comes with built-in support for LiveView apps. You can create a new application with:

mix phx.new my_app --live

Then add surface to the list of dependencies in mix.exs:

def deps do
  [
    {:surface, "~> 0.5.0"}
  ]
end

If you're using mix format, make sure you add :surface to the import_deps configuration in your .formatter.exs file:

[
  import_deps: [:ecto, :phoenix, :surface],
  ...
]

For further information regarding installation, including how to quickly get started using a boilerplate, please visit the Getting Started guide.

Migrating from v0.4.x to v0.5.x

Surface v0.5.0 introduces a new syntax which requires migrating components written in previous versions. In order to make the migration process as smooth as possible, Surface v0.5.x ships with a converter that can automatically translate the old syntax into the new one.

Please see the Migration Guide for details.

Tooling

• Surface Formatter - A code formatter for Surface.
• Surface package for VS Code - Syntax highlighting support for Surface/Elixir.

License

Copyright (c) 2020, Marlus Saraiva.

Surface source code is licensed under the MIT License.