File size: 6,944 Bytes
8e40013
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
---
title: "Next.js on \U0001F917 Spaces"
emoji: "\U0001F433\U0001F917"
colorFrom: blue
colorTo: yellow
sdk: docker
pinned: false
license: agpl-3.0
app_port: 3000
---
<h1 align="center">Next.js on πŸ€— Spaces</h1>

<p align="center">
Run your ML demo with ease in a <a href="https://nextjs.org">Next.js</a> environment
</p>

At failfast, we're passionate about crafting demos with TypeScript, Next.js, and MUI. Inspired by the ease-of-use of Gradio and Streamlit within Hugging Face Spaces, we aim to deliver a similar developer experience to JavaScript enthusiasts. Our toolkit includes predefined MUI components, empowering you to build intuitive UIs for your ML demos.

---

<!-- toc -->

- [Local development](#local-development)
  * [Use the Docker container locally](#use-the-docker-container-locally)
- [Secret Management](#secret-management)
  * [Build-time](#build-time)
  * [Runtime](#runtime)
- [Dockerize an existing project](#dockerize-an-existing-project)
- [Sync your GitHub repository with your πŸ€— Space](#sync-your-github-repository-with-your-%F0%9F%A4%97-space)
- [Cleanup your πŸ€— Space](#cleanup-your-%F0%9F%A4%97-space)
- [Development Roadmap](#development-roadmap)

<!-- tocstop -->

---

## Local development

1. Install the dependencies: `npm i`
2. Start the local dev-server: `npm run dev`
3. Open the app via [localhost:3000](http://localhost:3000)

### Use the Docker container locally

> ℹ️ In order for the commands to work, you need at least Docker >= 20.10, as we use env-variables as secrets

To make sure that everything is working out, you can run your container locally:

1. [Install Docker](https://docs.docker.com/get-docker/) on your machine
2. Go into the `nextjs-hf-spaces` folder
3. Build your Docker image: `docker build -t nextjs-hf-spaces .`
4. Run your Docker container: `docker run -p 3000:3000 nextjs-hf-spaces`.
5. Open the app via [localhost:3000](http://localhost:3000)

If you also have a secret that needs to be passed into the container, you can do this: 

1. Create a copy of `.env.local.example` and rename it to `.env.local` (it contains the secret `HF_EXAMPLE_SECRET`)
2. Run your Docker container and specify the env-file: `docker run -p 3000:3000 --env-file .env.local nextjs-hf-spaces`
3. Open the example API via [localhost:3000/api/env](http://localhost:3000/api/env) and see that the value of our secret `HF_EXAMPLE_SECRET` is shown

## Secret Management

To not expose your secrets to end users, you can add them directly in **Settings** of your πŸ€— Space.

1. Open your space and navigate to the **Settings**
2. Find **Repository secrets** & click on **New secret**
   
That's it, you can now access your secret.

### Build-time

If you need to have a secret during build-time (e.g. you want to install private npm packages), then you can add this directly into the `Dockerfile`:

```dockerfile
# Uncomment the following lines if you want to use a secret at buildtime, 
# for example to access your private npm packages
RUN --mount=type=secret,id=HF_EXAMPLE_SECRET,mode=0444,required=true \
    $(cat /run/secrets/HF_EXAMPLE_SECRET)
```

In this case, we mount the secret `HF_EXAMPLE_SECRET` (using [Docker secrets](https://docs.docker.com/engine/swarm/secrets/)) inside and can use it. 

### Runtime

When your πŸ€— Space is running and you want to use a secret (e.g. access an API that requires authentication) without exposing it to the user, you can use it as an environment variable via `process.env`. 

```typescript
import process from "node:process";
import { NextApiRequest, NextApiResponse } from "next";

export default async function handler(
  request: NextApiRequest,
  response: NextApiResponse
) {
  const exampleSecret = process.env.HF_EXAMPLE_SECRET;

  // Your logic to access an API that requires authentication

  return response.status(200).json("We have access to an external API");
}
```

A simple example can be found at [nextjs-hf-spaces/api/env](https://huggingface.co/spaces/failfast/nextjs-hf-spaces/api/env). This will return the secret to see that it's working, but you wouldn't do this in your space, as you don't want to expose the secret to an end user. 

## Dockerize an existing project

To add support for Docker to an existing project, just copy the `Dockerfile` into the root of the project and add the following to the `next.config.js` file:

```js
// next.config.js
module.exports = {
  // ... rest of the configuration.
  output: "standalone",
};
```

This will build the project as a standalone app inside the Docker image.

## Sync your GitHub repository with your πŸ€— Space

If you want to use all the features for collaborative development on GitHub, but keep your demo on πŸ€— Spaces, then you can set up a GitHub action that will automatically push changes from GitHub into Spaces.

> ℹ️ Git-LFS is required for files bigger than 10MB

1. Create your repo on GitHub
2. Create a [Github secret](https://docs.github.com/en/actions/security-guides/encrypted-secrets#creating-encrypted-secrets-for-a-repository) named `HF_TOKEN` and use an [access token from Hugging Face](https://huggingface.co/settings/tokens) as its value (you must be logged in to do this)
3. Update the workflow [sync_to_hf_spaces.yml](.github/workflows/sync_to_hf_spaces.yml)
   - Configure `HF_USERNAME`: Replace `failfast` with the name of your πŸ€— user account or your πŸ€— organization
   - Configure `HF_SPACE_NAME`: Replace `nextjs-hf-spaces` with the name of your πŸ€— space
4. Push the code into your repo on GitHub

This should force push changes in the **main** branch from GitHub into your πŸ€— space.

For further information, you can check out the [guide on Hugging Face](https://huggingface.co/docs/hub/spaces-github-actions).


## Cleanup your πŸ€— Space

You don't need all the demo content and examples? Then you can delete these resources to get a clean πŸ€— Space:

* `src/pages/api/env.ts`
* `src/components/example-components.tsx`
* `src/components/getting-started.tsx`
* `src/components/under-construction.tsx`
* `src/components/title.tsx`
* `src/components/huggingface/huggingface.tsx`

Update the `src/components/index.tsx` and remove:

```jsx
<Title />

<GettingStarted />

<DividerBox />

<ExampleComponents />
```

> i Got an idea how this could be better? Please let us know!

## Development Roadmap

The next milestones in no particular order are:

* Components for all [`@huggingface/inference`](https://huggingface.co/docs/huggingface.js/inference/README) methods (WIP)
* Components to use [langchain.js](https://js.langchain.com/docs)
* Components to use [hyv](https://github.com/failfa-st/hyv)
* Publish components on npm to make them usable outside of [nextjs-hf-spaces](https://github.com/failfa-st/nextjs-hf-spaces)
* Provide templates for different use-cases, that are too complex for single components
* Docs on how to use the components with all available options

> i Anything missing? Please let us know!