Fable: "Getting started" guide probably needed (also a weird error)

[boxed]

Description

I am trying to use fable to make a test web app. I have no previous experience with F# and am using Visual Studio for Mac for the first time. There's a lot of test on fable.io but nothing that seems to be a getting started guide really.

I created a blank console project and tried doing a fable compile and got

✗ fable FSharpTest.fsproj 
fable-compiler 0.7.42: Start compilation...
F# project contains errors:
/Users/boxed/Projects/FSharpTest/FSharpTest/Program.fs(L4,0) : error FSHARP: Files in libraries or multiple-file applications must begin with a namespace or module declaration, e.g. 'namespace SomeNamespace.SubNamespace' or 'module SomeNamespace.SomeModule'. Only the last source file of an application may omit such a declaration.

the error message seems wrong since there's exactly 1 file, so it should by definition be the last source file :P

Repro code

// Learn more about F# at http://fsharp.net
// See the 'F# Tutorial' project for more help.

[<EntryPoint>]
let main argv = 
    printfn "%A" argv
    0 // return an integer exit code

[boxed]

Further comments:

http://fable.io/docs/compiling.html#fable-core I have no idea what any of that means. What is a "module bundler"? What is AMD (except a CPU company)? You should probably target people who are coming to Fable because they don't want to deal with the JavaScript madness, and not people who are already good at it.

Same with http://fable.io/docs/compiling.html#Polyfill which is also a bunch of stuff I don't care about and don't want to know.. that's part of the reason I'm looking into Fable in the first place!

http://fable.io/docs/compiling.html#Modules You can guess my comment here too :P I don't want to know that stuff, I don't want to take a lot of decisions I'm not qualified to make, just tell me what to do.

The samples portion of the same page links to a samples download/repo that doesn't seem to have the Elm architecture variant of TodoMVC. So I have to copy paste and infer the missing parts from the samples page? :(

I believe this could be radically simplified to get up and running from scratch for people starting out or just wanting to check out if it's something to invest time in. A simple bash script would probably do. I would write it, if I understood any of that stuff... Instead I think I'll give up at this point and check back later to see if things have improved.

[alfonsogarciacaro]

Hi @boxed! Thanks a lot for your comments. Yeah, you're absolutely right that we're missing a more comprehensive step by step getting started tutorial. There's a getting started repo here but it probably doesn't answer all your questions.

About the error you got: Every error FSHARP comes from the F# compiler itself and not from Fable, so there's little you can do. If you think that's a bug, it probably should be reported to the F# team.

About the module bundlers, polyfills and such: Fable was designed to be integrated in modern JS development workflows so, although we should try to make this as easy as possible, some knowledge about the JS ecosystem is going to be necessary.

One of the biggest problems, as the one you mention with the TodoMVC sample, is Fable is evolving very quickly with the feedback from the users so do to my limited time availability is difficult to keep all the samples and docs up to date.

There're usually people in the Gitter channel willing to provide help, but if you feel that the workflow is still too rough (and you're probably right about that), it is probably ok to wait a bit until the dust settles down and Fable 1.0 is released (in one or two months), which I'm already working on.

[boxed]

That repo looks great! Seems also that it can be automated and fixed up with a simple bash script. Those directions I can follow to make that experience nicer I think.

I'll see what I can do, when I get time.

[boxed]

I've now made a PR for that repo to start a discussion of how to make it even better.

I think what is really needed is to point to this repo in the documentation though.

[simax]

Thanks for Fable, looks awesome.
I was also hoping to find the Elm architecture variant of TodoMVC.

[alfonsogarciacaro]

Hi @simax! There're two Fable projects inspired by Elm at the moment: fable-elmish which works with React and have almost the same API (I think) as Elm and fable-arch, which is also inspired by Elm but has a different API.

[simax]

Thanks, I'll check them out.

[Pauan]

@alfonsogarciacaro So when are we going to put a big huge flashing neon sign on fable.io which points to fable-getting-started? :stuck_out_tongue:

If you want, I can send a PR for it.

[alfonsogarciacaro]

Hmmm, I'm going to announce the release of Fable 1.0 beta and the there are many changes in the workflow so if you don't mind, we can wait until the release, update fable-getting-started and then add the big huge flashing neon sign ;)

[Pauan]

@alfonsogarciacaro Sure, sounds good.

[alfonsogarciacaro]

@Pauan Can you add a link to the getting-started repo in the awesome-fable list? Thx!