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 component API, 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.
# 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
-
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.
Phoenix v1.7 comes with built-in support for LiveView apps. You can create a new phoenix application with:
mix phx.new my_app
Note: In case you want to add Surface to an existing Phoenix application that doesn't have LiveView properly installed, please see Phoenix Liveview's installation instructions at hexdocs.pm/phoenix_live_view/installation.html.
Add surface
to the list of dependencies in mix.exs
:
def deps do
[
{:surface, "~> 0.11.0"}
]
end
After fetching the dependencies with mix deps.get
, you can run the surface.init
task to
update the necessary files in your project.
In case you want the task to also generate a sample component for you, use can use the --demo
option.
A liveview using the component will be available at the /demo
route.
Additionally, the task can also set up a Surface Catalogue
for your project using the --catalogue
option. The catalogue will be available at /catalogue
.
Note: When using the
--demo
and--catalogue
options together, the task also generates two catalogue examples and a playground for the sample component.
mix surface.init --demo --catalogue
Start the Phoenix server with:
mix phx.server
That's it! You can now access your application at https://localhost:4000.
You can see the full list of options provided by surface.init
by running:
mix help surface.init
For further information regarding installation, including how to install Surface manually, please visit the Getting Started guide.
Please see the Migration Guide for details.
- Surface Formatter - A code formatter for Surface.
- Surface package for VS Code - Syntax highlighting support for Surface/Elixir.
Copyright (c) 2020, Marlus Saraiva.
Surface source code is licensed under the MIT License.