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.
v0.4.x
to v0.5.x
Migrating from 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.