Skip to content

GETTING_STARTED.md

Latest commit

 

History

History
260 lines (167 loc) · 9.92 KB

GETTING_STARTED.md

File metadata and controls

260 lines (167 loc) · 9.92 KB
Raw

Getting Started with Forecone

A complete, beginner-friendly guide. If you've never run a project from GitHub before, this is written for you — every step is spelled out. By the end you'll have Forecone running on your own computer, and (optionally) deployed live on the internet for free.

It takes about 5–10 minutes for the basic setup.

What you'll end up with

Forecone running in your web browser at http://localhost:3000, where you can search any US stock, open its full analysis, play with the bull/base/bear valuation, and explore the Capital Flow maps.

There are two ways to use it — pick whichever fits you:

Just run it locally Deploy it online (free)
Where it runs Your own computer Vercel's servers, on a public URL
Best for Trying it, tinkering with the code Sharing a link, a live or demo site
Covered in Steps 1–4 below The Deploy your own section

Note

No API keys are required. Forecone works out of the box using free Yahoo Finance data. Keys are optional upgrades (covered later).

Step 0 — Install Node.js (one-time)

Forecone is built with Node.js. If you don't already have it, install it once and you're set.

  1. Go to nodejs.org.
  2. Download the LTS version (the big green button — currently 20.x or 22.x). LTS = "Long Term Support" = the stable one.
  3. Run the installer and click through with the defaults.

Check it worked. Open a terminal:

  • Windows — press Win, type PowerShell, press Enter.
  • Mac — press Cmd+Space, type Terminal, press Enter.
  • Linux — open your Terminal app.

Type this and press Enter:

node --version

You should see something like v20.11.0 (any number 18 or higher is fine). If you see a version number, you're good. If you get "command not found", close and reopen the terminal, or restart your computer so the install registers.

Tip

A terminal (also called a command line, shell, PowerShell, or Terminal) is just a text window where you type commands. You'll use it for the next few steps. To run a command, type it (or paste it) and press Enter.

Step 1 — Get the code

Pick one of these two options.

Option A — Download a ZIP (easiest, no extra tools)

  1. Go to github.com/nirravv/ForeCone.
  2. Click the green < > Code button → Download ZIP.
  3. Unzip it somewhere you'll remember (e.g. your Desktop). You'll get a folder named ForeCone-main.

Option B — Clone with Git (better if you'll update often)

If you have Git installed, run:

git clone https://github.com/nirravv/ForeCone.git

This creates a ForeCone folder with the code inside.

Now go into the folder

In your terminal, navigate into the project folder. cd means "change directory":

# If you cloned with Git:
cd ForeCone

# If you downloaded the ZIP, use the unzipped folder name, e.g.:
cd Desktop/ForeCone-main

Tip

Not sure of the path? On Windows you can type cd (with a space), then drag the folder from File Explorer into the terminal, and press Enter — it fills in the path for you.

Step 2 — Install the dependencies

This downloads the libraries Forecone needs. Run:

npm install

This takes 1–3 minutes the first time and prints a lot of text — that's normal. When it's done you'll have a new node_modules folder. You only need to do this once (and again after you update the code).

Note

Seeing yellow warn messages? Those are normal and safe to ignore. Only red ERR! messages that stop the install need attention — see Troubleshooting.

Step 3 — Run it 🎉

npm run dev

After a few seconds you'll see something like:

  ▲ Next.js 16
  - Local:   http://localhost:3000
  ✓ Ready in 2.1s

Open your browser and go to http://localhost:3000.

That's it — Forecone is running. Try searching for a ticker like NVDA or AAPL, or click Flow in the top menu to explore the Capital Flow maps.

Tip

The terminal needs to stay open while you use the app — it's running the server. To stop the app, click the terminal and press Ctrl + C. To start it again later, cd back into the folder and run npm run dev.

The first time you open a page it may take a moment to load while it fetches data; after that it's cached and fast.

Step 4 (optional) — Add a free Polygon key for live prices

Forecone works fine without any key (using delayed Yahoo Finance data). If you want real-time prices and charts, add a free Polygon.io key:

  1. Sign up at polygon.io (the free tier is enough to try it).

  2. From your dashboard, copy your API Key.

  3. In the project folder, create your settings file by copying the template:

    # Mac / Linux
cp .env.example .env.local

# Windows (PowerShell)
Copy-Item .env.example .env.local

  4. Open .env.local in any text editor (Notepad is fine) and paste your key:

    POLYGON_API_KEY=your_key_here

  5. Save the file, stop the app (Ctrl + C), and start it again (npm run dev).

Note

The free Polygon tier is rate-limited (~5 requests/minute), so heavy pages may briefly fall back to Yahoo. That's expected. Without a key, everything still works on Yahoo data.

Optional — a persistent cache (database)

Totally optional and not needed for normal use. If you want the data cache to survive restarts, add a free Neon Postgres database connection string to .env.local:

DATABASE_URL=your_neon_connection_string

Without it, Forecone uses an in-memory cache and works perfectly fine.

Deploy your own (free)

Want it live on the internet on its own URL? Vercel (the company behind Next.js) hosts Next.js apps for free.

It's the same code either way — one setting decides whether your deployment is the real app or a read-only demo.

A) Deploy the real app

  1. Push your copy to your own GitHub repository (or fork nirravv/ForeCone).
  2. Go to vercel.com/new and sign in with GitHub.
  3. Click Import next to your repository.
  4. (Optional) Under Environment Variables, add POLYGON_API_KEY for live prices.
  5. Click Deploy. After a minute you'll get a public URL like your-app.vercel.app.

B) Deploy the demo dashboard

The demo runs on fixed sample data baked into the project — no live data feed, no keys, nothing to break. It's perfect for sharing a link that always works. To deploy it, do everything in (A), plus one extra environment variable:

Name Value
NEXT_PUBLIC_DEMO 1

With that set, the deployment serves the snapshot data in public/demo/ and shows a "Demo dashboard" banner. (You can run the demo locally too: add NEXT_PUBLIC_DEMO=1 to your .env.local and run npm run dev.)

Tip

A common setup is two Vercel projects from the same repo: one without the flag (your live app, with your key) and one with NEXT_PUBLIC_DEMO=1 (a public demo). Both update automatically when you push code.

Refreshing the demo's sample data

The demo's numbers are a snapshot. To capture fresh ones:

npm run dev            # terminal 1 — leave it running (no key needed)
npm run snapshot:demo  # terminal 2 — captures ~70 tickers into public/demo/

Then commit the updated public/demo/ folder and redeploy. (Run this without a Polygon key — the free tier is too rate-limited for the bulk capture; the script uses keyless Yahoo.)

Troubleshooting

node or npm is not recognized / command not found Node.js isn't installed or the terminal hasn't picked it up yet. Re-do Step 0, then close and reopen the terminal (or restart your computer).

npm install fails with red ERR! messages

  • Make sure your Node.js version is 18 or higher: node --version.
  • Check your internet connection and try again.
  • Still stuck? Delete the node_modules folder and the package-lock.json file, then run npm install again.

"Port 3000 is already in use" Something else is using that port. Either stop the other program, or run Forecone on a different port:

# Mac / Linux
PORT=3001 npm run dev
# Windows (PowerShell)
$env:PORT=3001; npm run dev

Then open http://localhost:3001.

Pages are blank or stuck "Loading…" This usually means the data source is slow or temporarily rate-limited (especially on the free tiers). Wait a few seconds and refresh. If it persists, the public data sources may be throttling you — try again in a minute.

The demo (Vercel) shows no data Make sure the NEXT_PUBLIC_DEMO environment variable is set to 1 in your Vercel project settings, and that you redeployed after adding it. Also confirm the public/demo/ folder is committed to your repository.

Changes to .env.local don't take effect You must stop (Ctrl + C) and restart (npm run dev) the app after editing .env.local.

Updating to the latest version

If you cloned with Git:

git pull           # get the latest code
npm install        # install any new dependencies
npm run dev        # run it

If you downloaded a ZIP, download the latest ZIP again and re-run npm install.

Need help?

  • 🐛 Found a bug or have a question? Open an issue on GitHub.
  • 💡 Want a company added to Capital Flow, or another feature? Issues and pull requests are welcome — see the README.

Important

Forecone is for informational and educational purposes only and is not investment advice. Data may be delayed or inaccurate. Always do your own research.