Faran Butt
commited on
Commit
β’
666c2e2
1
Parent(s):
ba9b2e1
Updated Readme
Browse files
README.md
CHANGED
@@ -1,3 +1,175 @@
|
|
1 |
-
|
2 |
-
|
3 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
1 |
+
---
|
2 |
+
title: "Next.js on \U0001F917 Spaces"
|
3 |
+
emoji: "\U0001F433\U0001F917"
|
4 |
+
colorFrom: blue
|
5 |
+
colorTo: yellow
|
6 |
+
sdk: docker
|
7 |
+
pinned: false
|
8 |
+
license: agpl-3.0
|
9 |
+
app_port: 3000
|
10 |
+
---
|
11 |
+
<h1 align="center">Next.js on π€ Spaces</h1>
|
12 |
+
|
13 |
+
<p align="center">
|
14 |
+
Run your ML demo with ease in a <a href="https://nextjs.org">Next.js</a> environment
|
15 |
+
</p>
|
16 |
+
|
17 |
+
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.
|
18 |
+
|
19 |
+
---
|
20 |
+
|
21 |
+
<!-- toc -->
|
22 |
+
|
23 |
+
- [Local development](#local-development)
|
24 |
+
* [Use the Docker container locally](#use-the-docker-container-locally)
|
25 |
+
- [Secret Management](#secret-management)
|
26 |
+
* [Build-time](#build-time)
|
27 |
+
* [Runtime](#runtime)
|
28 |
+
- [Dockerize an existing project](#dockerize-an-existing-project)
|
29 |
+
- [Sync your GitHub repository with your π€ Space](#sync-your-github-repository-with-your-%F0%9F%A4%97-space)
|
30 |
+
- [Cleanup your π€ Space](#cleanup-your-%F0%9F%A4%97-space)
|
31 |
+
- [Development Roadmap](#development-roadmap)
|
32 |
+
|
33 |
+
<!-- tocstop -->
|
34 |
+
|
35 |
+
---
|
36 |
+
|
37 |
+
## Local development
|
38 |
+
|
39 |
+
1. Install the dependencies: `npm i`
|
40 |
+
2. Start the local dev-server: `npm run dev`
|
41 |
+
3. Open the app via [localhost:3000](http://localhost:3000)
|
42 |
+
|
43 |
+
### Use the Docker container locally
|
44 |
+
|
45 |
+
> βΉοΈ In order for the commands to work, you need at least Docker >= 20.10, as we use env-variables as secrets
|
46 |
+
|
47 |
+
To make sure that everything is working out, you can run your container locally:
|
48 |
+
|
49 |
+
1. [Install Docker](https://docs.docker.com/get-docker/) on your machine
|
50 |
+
2. Go into the `nextjs-hf-spaces` folder
|
51 |
+
3. Build your Docker image: `docker build -t nextjs-hf-spaces .`
|
52 |
+
4. Run your Docker container: `docker run -p 3000:3000 nextjs-hf-spaces`.
|
53 |
+
5. Open the app via [localhost:3000](http://localhost:3000)
|
54 |
+
|
55 |
+
If you also have a secret that needs to be passed into the container, you can do this:
|
56 |
+
|
57 |
+
1. Create a copy of `.env.local.example` and rename it to `.env.local` (it contains the secret `HF_EXAMPLE_SECRET`)
|
58 |
+
2. Run your Docker container and specify the env-file: `docker run -p 3000:3000 --env-file .env.local nextjs-hf-spaces`
|
59 |
+
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
|
60 |
+
|
61 |
+
## Secret Management
|
62 |
+
|
63 |
+
To not expose your secrets to end users, you can add them directly in **Settings** of your π€ Space.
|
64 |
+
|
65 |
+
1. Open your space and navigate to the **Settings**
|
66 |
+
2. Find **Repository secrets** & click on **New secret**
|
67 |
+
|
68 |
+
That's it, you can now access your secret.
|
69 |
+
|
70 |
+
### Build-time
|
71 |
+
|
72 |
+
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`:
|
73 |
+
|
74 |
+
```dockerfile
|
75 |
+
# Uncomment the following lines if you want to use a secret at buildtime,
|
76 |
+
# for example to access your private npm packages
|
77 |
+
RUN --mount=type=secret,id=HF_EXAMPLE_SECRET,mode=0444,required=true \
|
78 |
+
$(cat /run/secrets/HF_EXAMPLE_SECRET)
|
79 |
+
```
|
80 |
+
|
81 |
+
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.
|
82 |
+
|
83 |
+
### Runtime
|
84 |
+
|
85 |
+
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`.
|
86 |
+
|
87 |
+
```typescript
|
88 |
+
import process from "node:process";
|
89 |
+
import { NextApiRequest, NextApiResponse } from "next";
|
90 |
+
|
91 |
+
export default async function handler(
|
92 |
+
request: NextApiRequest,
|
93 |
+
response: NextApiResponse
|
94 |
+
) {
|
95 |
+
const exampleSecret = process.env.HF_EXAMPLE_SECRET;
|
96 |
+
|
97 |
+
// Your logic to access an API that requires authentication
|
98 |
+
|
99 |
+
return response.status(200).json("We have access to an external API");
|
100 |
+
}
|
101 |
+
```
|
102 |
+
|
103 |
+
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.
|
104 |
+
|
105 |
+
## Dockerize an existing project
|
106 |
+
|
107 |
+
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:
|
108 |
+
|
109 |
+
```js
|
110 |
+
// next.config.js
|
111 |
+
module.exports = {
|
112 |
+
// ... rest of the configuration.
|
113 |
+
output: "standalone",
|
114 |
+
};
|
115 |
+
```
|
116 |
+
|
117 |
+
This will build the project as a standalone app inside the Docker image.
|
118 |
+
|
119 |
+
## Sync your GitHub repository with your π€ Space
|
120 |
+
|
121 |
+
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.
|
122 |
+
|
123 |
+
> βΉοΈ Git-LFS is required for files bigger than 10MB
|
124 |
+
|
125 |
+
1. Create your repo on GitHub
|
126 |
+
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)
|
127 |
+
3. Update the workflow [sync_to_hf_spaces.yml](.github/workflows/sync_to_hf_spaces.yml)
|
128 |
+
- Configure `HF_USERNAME`: Replace `failfast` with the name of your π€ user account or your π€ organization
|
129 |
+
- Configure `HF_SPACE_NAME`: Replace `nextjs-hf-spaces` with the name of your π€ space
|
130 |
+
4. Push the code into your repo on GitHub
|
131 |
+
|
132 |
+
This should force push changes in the **main** branch from GitHub into your π€ space.
|
133 |
+
|
134 |
+
For further information, you can check out the [guide on Hugging Face](https://huggingface.co/docs/hub/spaces-github-actions).
|
135 |
+
|
136 |
+
|
137 |
+
## Cleanup your π€ Space
|
138 |
+
|
139 |
+
You don't need all the demo content and examples? Then you can delete these resources to get a clean π€ Space:
|
140 |
+
|
141 |
+
* `src/pages/api/env.ts`
|
142 |
+
* `src/components/example-components.tsx`
|
143 |
+
* `src/components/getting-started.tsx`
|
144 |
+
* `src/components/under-construction.tsx`
|
145 |
+
* `src/components/title.tsx`
|
146 |
+
* `src/components/huggingface/huggingface.tsx`
|
147 |
+
|
148 |
+
Update the `src/components/index.tsx` and remove:
|
149 |
+
|
150 |
+
```jsx
|
151 |
+
<Title />
|
152 |
+
|
153 |
+
<GettingStarted />
|
154 |
+
|
155 |
+
<DividerBox />
|
156 |
+
|
157 |
+
<ExampleComponents />
|
158 |
+
```
|
159 |
+
|
160 |
+
> i Got an idea how this could be better? Please let us know!
|
161 |
+
|
162 |
+
## Development Roadmap
|
163 |
+
|
164 |
+
The next milestones in no particular order are:
|
165 |
+
|
166 |
+
* Components for all [`@huggingface/inference`](https://huggingface.co/docs/huggingface.js/inference/README) methods (WIP)
|
167 |
+
* Components to use [langchain.js](https://js.langchain.com/docs)
|
168 |
+
* Components to use [hyv](https://github.com/failfa-st/hyv)
|
169 |
+
* Publish components on npm to make them usable outside of [nextjs-hf-spaces](https://github.com/failfa-st/nextjs-hf-spaces)
|
170 |
+
* Provide templates for different use-cases, that are too complex for single components
|
171 |
+
* Docs on how to use the components with all available options
|
172 |
+
|
173 |
+
> i Anything missing? Please let us know!
|
174 |
+
|
175 |
+
|